talonic_invoke_agent_tool
Invoke one named tool from the platform's agent tool registry directly, with no model in the loop — you choose the arguments. This is how an external agent uses Talonic's retrieval and provenance while driving control flow itself: query_data for a read-only SQL SELECT over the extracted data, describe_data for the queryable field list, get_document_markdown to read a document's text. Denied capabilities come back as an error naming the capability required; the platform re-checks every call.
When to use
talonic_list_agent_toolsshowed a tool withcan_invoke: truethat does what you need.
When not to use
- Anything a dedicated
talonic_*tool already does — prefer those.
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Tool name, e.g. `query_data`. |
| args | object | Arguments matching the tool's `input_schema`. |
| document_ids | string[] | Hard scope for scope-aware tools. |
Response shape
Fields
| Parameter | Type | Description |
|---|---|---|
| tool | string | The tool that ran. |
| result | any | The tool's parsed output. |
| citations / artifacts / cards | array | Present when the tool attached them. |
Tool input
{ "name": "query_data", "args": { "sql": "SELECT field_key, count(*) FROM cells GROUP BY 1 ORDER BY 2 DESC LIMIT 5" } }Tool response
{
"tool": "query_data",
"result": { "rows": [{ "field_key": "invoice_number", "count": 412 }], "row_count": 1 }
}Frequently asked questions
Does invoking a tool cost credits?+
No. Every tool an API key can reach is LLM-free, so there is no model call to meter; the route is bounded by its own rate-limit namespace instead.