Package ai.mindconnect.agent.tool

Interface ToolAdvisor

public interface ToolAdvisor

Filter chain around every tool invocation.

The runtime walks all ToolAdvisor beans (in order() order) wrapped around a single tool call: each advisor sees the ToolAdvisor.Invocation on the way in and the ToolAdvisor.Result on the way out, and may mutate either. Calling chain.proceed(inv) runs the next advisor down — or, at the tail, the actual Tool.execute(Map).

Typical uses:

• Append progress hints (e.g. open-todo counter after every call) by intercepting the result and ToolAdvisor.Result.append(java.lang.String)-ing.
• Sanitize arguments before they reach the tool (block dangerous bash patterns, normalise paths).
• Redact PII from the result text (email addresses in Gmail responses, secrets in shell output).
• Short-circuit with a synthetic result without calling ToolAdvisor.Chain.proceed(ai.mindconnect.agent.tool.ToolAdvisor.Invocation) at all (rate limiting, permission denied).
• Audit / wire-trace by reading the ToolAdvisor.Invocation + ToolAdvisor.Result and proceeding unchanged.

An advisor that doesn't apply to the current call is skipped entirely. Throwing from around(ai.mindconnect.agent.tool.ToolAdvisor.Invocation, ai.mindconnect.agent.tool.ToolAdvisor.Chain) is propagated to the runtime's standard tool-failure path (no extra try/catch in advisor code).

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ToolAdvisor.Chain	Continuation handle.
static final record	ToolAdvisor.Invocation	Everything the runtime knows about one tool call.
static final record	ToolAdvisor.Result	What the LLM ends up seeing.

Method Summary

Modifier and Type	Method	Description
default boolean	applies(ToolAdvisor.Invocation inv)	Per-call opt-out.
ToolAdvisor.Result	around(ToolAdvisor.Invocation inv, ToolAdvisor.Chain chain)	Wraps one tool invocation.
default int	order()	Lower runs further out — sees raw input and final output.

Method Details

around

ToolAdvisor.Result around(ToolAdvisor.Invocation inv,
 ToolAdvisor.Chain chain)
                   throws Exception

Wraps one tool invocation. Must call chain.proceed(inv) unless the advisor is intentionally short-circuiting.

Throws:

Exception

order

default int order()

Lower runs further out — sees raw input and final output. Negative values are allowed. Default 0 = middle of the chain.

applies

default boolean applies(ToolAdvisor.Invocation inv)

Per-call opt-out. The runtime skips this advisor when it returns false, jumping straight to the next one. Lets advisors keep scope-checks (specific tool name, specific agent) outside of around(ai.mindconnect.agent.tool.ToolAdvisor.Invocation, ai.mindconnect.agent.tool.ToolAdvisor.Chain) for cheaper short-circuiting.