Designing Tools
A tool is the agent's only way to act on the world, and the model reads its definition to decide when and how to use it. Anthropic describes this as the agent-computer interface, and says it deserves the same care as a human-computer interface. Most failures that look like model problems are tool design problems.
Five parts of a good tool
Each tool definition is a contract. Treat it like a docstring you would write for a new engineer joining the team.
- Name. Use a verb and a noun that describe one action, such as
get_invoice. - Description. Say what it does, when to use it, and when not to use it. Naming the alternative tool prevents confusion.
- Parameters. Describe each one with its format and an example. Ambiguous names invite wrong arguments.
- Return value. Return only what the next decision needs. Large raw payloads waste the context budget.
- Errors. Return a message that says what went wrong and what to try next.
{
"name": "get_invoice",
"description": "Fetch one invoice by its ID. Use when the user gives an invoice number such as INV-2026-0042. Do not use to search by customer; use search_invoices for that.",
"input_schema": {
"type": "object",
"properties": {
"invoice_id": {
"type": "string",
"description": "Invoice ID in the form INV-YYYY-NNNN"
}
},
"required": ["invoice_id"]
}
}
Notice what the description does. It states the trigger, the boundary with a neighboring tool, and the expected input format. An engineer reading only this definition could call the tool correctly.
Make mistakes hard to make
Anthropic calls this poka-yoke, after the manufacturing practice of designing errors out. The SWE-bench team found that an agent made mistakes with relative file paths once it had moved out of the root directory. They changed the tool to require absolute paths, and the model used the new form without error. Ask yourself which argument the model could get wrong, then change the tool so that the wrong value is impossible or rejected with a clear message.
Practice
- Take a function you already have in your codebase. Rewrite its description following the five parts above.
- Give the tool five realistic inputs, including one with a typo and one that should fail. Record each mistake the model makes.
- Change one thing per iteration, such as a parameter description or an error message, and rerun the five inputs. Keep the change only if the mistakes drop.
Retrieval check
Two tools overlap in purpose, and the agent sometimes picks the wrong one. What is the first fix?
Correct. Overlap is a defect in the interface. Clarify the boundary in the tools themselves before adding instructions around them.
Not quite. A raised step limit or more prompt text will not fix an ambiguous choice. The boundary belongs in the tool definitions.
A lookup tool finds no matching record. Which result should it return?
Correct. An actionable message lets the model recover, for example by searching instead. An empty string gives it nothing to reason about.
Not quite. A silent or fatal result leaves the model without a path forward. A clear message that names the next step lets it recover.