Finding and running a tool

Three helpers an agent uses before anything else. Only a small window of tools is advertised by default; these are how the rest are found, read and invoked.

Permission is what the tool server requires before it dispatches; who holds it is read from the control plane’s own grant. The two are read from different places on purpose: a tool server that grants more than the control plane does offers an operation and then has it refused halfway through a conversation.

Advertised says whether the tool appears in the default tool list. Most do not: a small window is advertised and the rest are found with search_tools, read with describe_tool and invoked with request_tool. A tool reached that way is checked against the same permission as a direct call.

Generated from Tool. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

Tool	Permission	Who holds it	Advertised
describe_tool	none — any authenticated caller	every role	yes
request_tool	none — any authenticated caller	every role	yes
search_tools	none — any authenticated caller	every role	yes

describe_tool

Return the full input schema for one tool by name (use after search_tools).

Argument	Type	Required	Meaning
name	string	yes	—

request_tool

Invoke an operation that is not in the visible window: { name, args }. Subject to the same RBAC and confirmation as a direct call.

No permission of its own. It is not an operation of its own: the server intercepts it in the CallTool dispatch and runs the tool named in its arguments, which is then checked against that tool’s own permission. Gating request_tool itself would gate the act of asking rather than the act performed.

Argument	Type	Required	Meaning
name	string	yes	—
args	object	no	—

search_tools

Find operations by intent or keyword. Returns candidate tool names + summaries (no schemas, no side effects). Use describe_tool for a candidate’s full schema, then request_tool to run it.

Argument	Type	Required	Meaning
query	string	yes	—
limit	number	no	—