Invoke a Tool
POST /v1/agent/tools/:name/invoke runs one named agent tool with no model in the loop: scoped, capability-gated, credit-free, with raw output and citations.
POST /v1/agent/tools/:name/invoke runs one named tool directly, with no model in the loop: you supply the arguments the agent would otherwise have chosen, and you get the tool's raw output back. This is the seam for building your own agent on top of Talonic: your orchestrator owns the control flow and picks the tools, while Talonic supplies the retrieval planes, the structured cell reads, and the provenance. Where [POST /v1/ask](post-ask) is a full turn (plan, retrieve, answer, verify), a tool invocation is a single deterministic step out of that repertoire.
Discovery and invocation pair up: [GET /v1/agent/tools](agent-tools) lists every registered tool with its input_schema (a JSON Schema for args) and a can_invoke flag stating whether your key can run it. The same capability matrix the agent loop applies governs this route, so an API key, which runs as the least-privilege viewer role, can invoke only the read subset. A tool outside that subset answers 403 naming the capability it requires, so the refusal tells you what is missing rather than leaving you to guess across 61 tools.
The optional scope and on_behalf_of fields behave exactly as on POST /v1/ask: the scope compiles into a SQL predicate that bounds what the tool can read, with the same field set and the same caps, and on_behalf_of applies a named workspace user's compartment visibility to the invocation. That symmetry matters when you drive tools yourself, because it means a custom orchestrator inherits the same isolation guarantees a full ask gets. See [Scope, Models & Access](ask-scoping) for the full semantics.
agent_tools, and by the agent's per-tenant in-flight ceiling instead. This is a statement about the invocable set as it stands, not a promise that every future tool will be free: what holds is that a tool reachable through this route without a charge does no model work./v1/agent/tools/:name/invokeRequest body (JSON)
curl
Response
Response fields
Response
{
"tool": "query_data",
"ok": true,
"content": "[{\"vendor\":\"Northwind Supplies Ltd\",\"sum\":48200}]",
"cards": [],
"artifacts": [],
"citations": []
}Errors
The error contract is deliberately three-way, so an orchestrator can branch without parsing messages. 404 means no tool carries that name: consult GET /v1/agent/tools for the live registry. 403 means the tool exists but requires a capability the key's role does not grant; the message names the capability and points at can_invoke. 422 means the tool ran and failed on its own terms, with the tool's failure summary as the message; a 200 never carries a failure.
Error responses