Tools
What ends up in an agent's toolbox, how risky each tool is, and how an agent finds the one it needs.
An agent's tools are not configured. They are derived from its roles every time they are
needed: each action a role grants becomes a callable tool with a generated input schema, and
nothing the roles do not grant is ever offered. Because the derivation is the same everywhere,
the agent's own loop, GET /agent/tools and an MCP client's tools/list always agree.
invoices, vendors, payments). Your app has only the tables you create, so put your own table and column names in their place. About the example appThe list is a guide, not the gate. Every call is checked against policy again when it runs, along with the table's locks and column redaction, so a tool that slipped onto a stale list is still refused.
What can be in the toolbox
Your tables
For every table where a role grants an operation, and the operation is not locked on the table,
the agent can perform it: list, get, create, update or delete. In a conversation these are five
generic tools that take the table as an argument, so the toolbox does not grow with your
schema. Over MCP and REST each operation is its own tool, named <table>_<verb>:
invoices_list, invoices_get, invoices_create, invoices_update, invoices_delete.
Rows are addressed by uid, and a reference to another row is written as <thing>_uid, never
as a numeric id. Create and update take their columns under values:
{ "values": { "invoice_number": "INV-1042", "amount": 1200, "vendor_uid": "0199a3c2-7f1e-7b4a-9c3d-5e8f2a1b6c90" } }Your endpoints
A custom endpoint you built becomes a tool when two things are true: you ticked Expose as agent tool on it (under Endpoints), and a role grants its policy action. When you expose one you also give it a tool name, a description telling the agent when to use it, and a risk level.
This is the cleanest way to give an agent real power safely. "Refund this order, up to its
captured amount" written once as a handler that enforces its own rules is a far better grant
than orders:update. See Custom actions.
Analysis tools
When a role lets the agent list at least one table, it also gets tools that answer questions without pulling every row through the model:
| Tool | What it does |
|---|---|
aggregateRecords | Count, sum, average, min, max and distinct counts, with group-by and by-day/week/month, computed in the database. |
summarize | Profiles a table in one call: row count and a per-column summary. |
semanticAnalyze | Labels rows by reading their text (sentiment, theme, category) and returns counts per label. |
digest | Describes in prose what a set of rows is about. |
extractFields | Pulls structured values (an amount, a due date) out of free text. |
chartData | Builds a chart from a table by naming what to plot. |
Charts an agent makes appear in the app's Charts section. Sharing a chart as a public link
is a high risk action, so it halts for approval.
Built-in tools
findCapabilityis always present. See Finding the right tool.revertChangesis present whenever the agent can write. It undoes a write the agent made earlier in the conversation. See Undoing a write.
Outside tools
Tools from a third-party MCP server your organization has connected, bound to this app and granted by a role. Their names and schemas are the server's own. See Tool servers.
Risk levels
Every tool has a risk level, and the rule is short: low runs; moderate and high halt for
approval, unless the agent is set to auto-approve risky actions.
| Tool | Default risk |
|---|---|
| List or get a row | low |
| Create or update a row | moderate |
| Delete a row | high |
| Any write addressing more than 25 rows in one call | high |
Analysis tools, findCapability | low |
revertChanges | The risk of the writes it would make: undoing a create is a delete |
| A custom endpoint | The level you chose when you exposed it |
| A tool from a tool server | The level you set when you reviewed it. A new tool is given a cautious starting level from its name, and high when it cannot be classified |
Set an endpoint's risk deliberately
A newly exposed endpoint starts at Moderate, so it pauses for approval; lower it to Low only for calls that are safe to run unattended. For anything that writes, sends, charges or deletes, keep Moderate or choose High before you grant it to an agent.
Risk decides whether a granted step pauses. It never decides whether a step is allowed: that is the role's job, and a step the role does not grant is refused at any risk level.
Finding the right tool
An agent with a broad role can hold many tools, and a model that skims a long list will
sometimes conclude a tool is missing when it is not. findCapability closes that gap. The
agent states what it is trying to do in plain words ("refund an order", "remove a member") and
gets back the matching tools it actually holds, with their input schemas, ready to call.
It searches the agent's real grant, so it is also the authority on refusals: the agent is instructed to search, and search again with different words, before telling anyone it cannot do something.
It is also how very large toolboxes stay workable. When an app has more than 25 granted tools
from tool servers, they are left out of the agent's working list and reached through
findCapability instead. Their governance does not change.
Seeing the toolbox
curl "$AUTHORIC_URL/$APP_UID/agent/tools/invoices_delete" \
-H "Authorization: Bearer $AGENT_KEY"{
"ok": true,
"tool": {
"name": "invoices_delete",
"title": "Delete a row from invoices",
"description": "Delete a row by its uid from the \"invoices\" table.",
"inputSchema": {
"type": "object",
"properties": { "uid": { "type": "string" }, "deleteStrategy": { "type": "string" } },
"required": ["uid"]
},
"annotations": {
"title": "Delete a row from invoices",
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
},
"_meta": { "authoric.ai/riskLevel": "high" }
}
}A tool the agent does not hold is 404, the same answer as a tool that does not exist. The
annotations and _meta fields are explained on MCP server.