Tools
A tool is one operation of a connected system, such as "create a purchase order" in your ERP, that an agent can ask to run. Agents can only use tools you've added, and only as your policy allows. You manage them under Tools & agents → Tools.
Add tools
Tools come from a connection's API description, imported from an OpenAPI document or described in the console. If the connection has neither yet, see Connect a system.
- Open Tools & agents → Tools and click Add tools.
- Choose the Connection.
- Tick the operations agents may use. Each one shows its name, risk, request (method and path) and description. To find them in a long description, search (every word must appear in the name, tool id, request or description) or filter by risk. What you ticked stays ticked when the search hides it or you change page.
- Click Add selected tools.
The list shows only supported operations that aren't tools yet. Operations marked Not supported at import can't become tools.
Find a tool
The Tools list shows 25 tools a page. With more than that, choose 25, 50, 100, 150 or 200 under Per page, and move between pages with Previous and Next. To narrow it:
- Search: words that must all appear in the tool's name, id or request.
- Risk: read, write or high.
- On and off: only tools that are on, or only tools that are off.
Add only what agents need. An operation you don't add can't be called by any agent, whatever the policy says.
A new tool is available at once, but no agent can use it until a policy rule allows it. With no matching rule, calls are denied. See Write a policy.
Tool ids
Each tool has an id made of the connection's system key and the operation's name, for example:
erp.inventory.listerp.purchase_orders.create
The operation's name comes from its operationId in the API description, in lowercase. Without one, Gatelion builds it from the method and path. For an API described in the console, it's the operation's Tool id.
Tool ids are what your policy names and what agents call, so they're exact and case-sensitive. The Tools list shows each tool's display name with its id below it.
Risk
Every tool has a risk, shown in the Risk column:
| Risk | Default for | How the Gateway treats it |
|---|---|---|
| Read | GET operations | Reads data. Can run with configuration up to the read window old (1 hour by default). |
| Write | POST, PUT and PATCH operations | Changes data. Needs fresher configuration (15 minutes by default), is never retried, and is marked unknown if the result is uncertain. |
| High risk | DELETE operations | Handled like a write. The label tells policy authors and approvers to take extra care. |
You can set a different risk for an operation with the x-gatelion-risk extension in its API description, then re-import. An operation can be raised to write or high, but only GET operations can be read. For an API described in the console, choose the Risk on the operation instead. See OpenAPI extensions.
Risk doesn't decide whether a call is allowed. Your policy does.
Versions
The Version column shows the tool's current version. When you re-import a changed API description, each tool whose operation changed gets a new version, and its pending approvals are cancelled (tool_changed). See Re-import a changed description.
Switch a tool off
The Available switch on each row is the tool's kill switch. Turn it off, then confirm with Stop tool, to stop every agent using that tool, whatever the policy says. Gateways apply it on their next sync, normally within about 15 seconds.
- Agents no longer see the tool, and calls to it are denied as
unknown_tool. - Requests for the tool that are waiting for approval, or approved but not yet running, are cancelled at once. They show as Cancelled in Approvals, and the agent gets
rejectedwithtool_disabled. Turning the tool on again doesn't bring them back; the agent has to ask again. - Turn the switch on again to make the tool available.
Timeouts and response size
Each tool has limits, set when it's imported:
| Limit | Default for reads | Default for writes | Range |
|---|---|---|---|
| Timeout | 5 seconds | 10 seconds | 1–60 seconds |
| Largest response | 256 KB | 64 KB | 1 KB–1 MB |
The Gateway uses the shorter of the tool's timeout and the connection's Timeout (ms). To change a tool's limits, set x-gatelion-timeout-ms or x-gatelion-max-response-bytes in the API description and re-import. Tools of an API described in the console always get the defaults.
When a limit is hit:
- A read fails. The agent can try again.
- A write is marked Unknown: reconcile, because the system may have done it. It's never sent again automatically. Someone has to check the system. See Executions and audit.
Each tool can also be called at most 60 times a minute per agent, on top of the agent's own limit.
What agents see
When an agent connects, it gets a list of tools. The list contains:
get_execution_status, the status tool, always.- Each tool that is switched on and that your policy could let this agent run. Tools the policy always denies to this agent aren't listed, and calling them gives
unknown_tool, as if they didn't exist.
For each tool, the agent sees its id, its description from the API description, and the arguments it takes. The arguments are checked strictly: unknown fields and wrong types are refused before the policy is even asked.
The agent gets back only the result fields the API description declares, without fields that look sensitive. You can choose them with x-gatelion-output-fields and x-gatelion-sensitive-fields.
If a Gateway is stopped, or its configuration is too old, agents see only the status tool. See Calling tools.
What approvers see
When a call needs approval, approvers see the tool's approval view: a title and the request's most important values with labels, followed by the exact arguments. By default the title is the tool's name, and the fields are its path parameters and required arguments (up to eight). Amounts are formatted as money when the description marks them.
To choose the title, labels and fields yourself, add x-gatelion-display to the operation. See OpenAPI extensions and Decide approvals.
Related: Connect a system · Write a policy · Agents and tokens
Still stuck? Contact support from the console.