Design each tool as one business action, not a door into a system. "Issue refund for order, amount, reason" is a tool; "send any request to the payments API" is not. Give it narrow, typed inputs, declare whether it can be undone, return a clear result, and register it against one capability so every call can be checked and recorded.
Why does tool design matter so much?
Tools are the only way an agent touches the world. Everything the governing layer can check is shaped by how tools are defined. A tool that does one thing with three parameters can be bounded precisely: by amount, by record, by reversibility. A tool that accepts a free-form request cannot, because the platform cannot tell in advance what the call will do.
Tool design also shapes how well the agent behaves. The model chooses tools from their names and descriptions. Clear, distinct tools are chosen correctly more often than overlapping, generic ones. The mechanics are covered in how an AI agent uses tools.
What are the steps, and who acts?
- Name the business action. The process owner says what the agent needs to do in business terms: change a delivery address, waive a late fee. Evidence: a capability entry in the role.
- Define inputs narrowly. The developer specifies typed parameters with limits: an order identifier, an amount with a maximum, a reason from a fixed list. No free text where a choice will do. Evidence: the tool's schema.
- Declare reversibility and depth. The process owner and risk owner agree whether the action can be undone and which depth it needs. Evidence: the depth assigned in the tool registry.
- Write the description for the model. The developer explains what the tool does, when to use it and when not to. Evidence: the description version.
- Return structured results. The tool reports what changed, the new state and any reference. It never returns "done" without detail. Evidence: result schema.
- Make it safe to repeat. Each call carries an idempotency key, so a retry does not refund twice. Evidence: idempotency tests.
- Provide a draft mode for depth-2 use, which prepares the action without performing it. Evidence: the draft and live variants in the registry.
- Register and approve. The system owner approves the connection; the tool is mapped to one capability. Evidence: the connection record.
What does a good tool look like next to a poor one?
| Poor design | Better design |
|---|---|
call_payments_api(request) |
issue_refund(order_id, amount, reason_code) |
update_customer(fields) |
change_delivery_address(customer_id, address_id) |
run_sql(query) |
get_overdue_balance(account_id) |
| Returns "OK" | Returns refund reference, amount, new order balance |
| One tool for read and write | Separate read and write tools at different depths |
The last row is easy to miss. If reading a balance and changing it share a tool, an agent certified to depth 1 for reading cannot be given the tool at all.
What does this look like in practice?
Take an online retailer whose support agent handles delivery problems. The first draft gave the agent a general order-update tool. It could change addresses, cancel lines and alter prices, and there was no way to allow one without the others.
The redesign split it into four tools: look up order, change delivery address to an address already on the account, cancel an unshipped line, and issue a goodwill credit up to a limit with a reason code. Each maps to one capability with its own depth. Address changes to a new address became a separate draft-only tool, held for a person, because that is a common fraud route. The agent's behaviour improved too: with distinct tools, it stopped trying to fix delivery issues by editing prices.
Where should tools sit relative to the gateway?
Tools usually call systems through an API gateway, which handles transport, rate limits and system credentials. The governing layer decides whether the call may happen; the gateway carries it. How to set that up is covered in how to put an API gateway in front of an AI agent's tools. The broader rule on tool count is in how many tools an AI agent should have, and the agent integration design template gives a format for documenting each one.
The full design of the governing layer is in the governed agentic operating system guide.
Questions people ask
Should tools enforce limits themselves?
Tools should validate their inputs, such as rejecting a negative amount. Business limits, such as a daily refund cap, belong in the governing layer, so they are held in one place and apply whichever tool is used.
Can an agent create its own tools?
It should not create tools that act on live systems. New tools change what an agent can do, so they go through the same approval as any new connection.
How detailed should tool descriptions be?
Detailed enough that a new colleague could pick the right tool from the description alone, including when not to use it. Avoid instructions about permissions; those are enforced, not described.