Designing tools for agents
Your code does the same thing every time for the same input. The model does not. A tool is the agreement between them, so design it for the model, not for a human developer.
Words on this page (5)
- tool
- : A function the model can ask your program to run, described by a name, description and argument schema.
- API
- : Application programming interface: a way for one program to call another, usually over HTTP.
- token
- : A piece of text the model reads and writes, usually a word or part of a word. About 4 characters of English on average.
- schema
- : A description of the shape of data: which fields exist and what types they have.
- attention
- : The mechanism that lets each token weigh all earlier tokens by relevance when computing its next representation.
Principles
Fewer, higher-level beat many thin ones. A single "search customers by name" tool is easier to use well than five separate calls the model must string together. Write descriptions as if for a new colleague, with when to use it and examples. Return what the model needs, in readable form, not raw database rows ("Order 8123, shipped Tuesday, $42" rather than every column). Offer filters, or return only a few results at a time, so a call cannot return 40,000 . Make errors instructive: say what failed and what to try.
Test them with the model
Run realistic tasks, read the transcripts, and look for confusion. Common signs are wrong tool picks, wrong arguments and over-calling (using a tool when it is not needed). Revise descriptions and responses, then rerun the same tasks and compare.
A worked example: a tool description
Weak: "search - searches stuff". Better: "search_orders - find orders for a customer. Use when the user asks about past purchases. Input: customer_email (required), status (optional: open, shipped, cancelled). Returns up to 5 orders as id, date, total, status." The better one tells the model when to use it, what to pass and what comes back.
How the model sees your tools
The model never sees your code. It sees each tool's name, description and argument as text, and your program sends all of them on every call. Invented numbers: 30 tools at 150 tokens each is 4,500 tokens of definitions per call. A task with 10 calls resends 45,000 tokens of tool text before any real work.
Size is only one side. With 30 similar options, the model has more chances to pick the wrong one. This is part of why fewer, clearer tools work better.
What goes wrong: overlapping tools
You have search_customers and find_user, and both can look up a person by email. The symptom is that the model picks one on Monday and the other on Tuesday, or picks whichever name sounds nicer. Confirm it by asking the same ten questions and tallying which tool is called. If one question splits close to evenly, the tools overlap. Merge them, or write in each description when it should not be used.
When fewer tools goes too far
Taken to the extreme, you could offer one tool, do_anything(action, params). Its schema says nothing about what is valid, so you cannot validate arguments. You also cannot allow reading while blocking deleting, because every action looks the same. Merge tools that do the same job. Keep separate the ones with different risks, such as read_order and cancel_order.
Common mistake
Returning raw database dumps. Shape the result for a reader with limited .
A shop gives its assistant two tools: get_order and cancel_order. A third tool, run_sql, is tempting because it can do everything, but it makes the assistant likely to write risky queries. Fewer, safer tools that match real tasks work better than one super tool.
Check yourself
What is wrong with a tool that returns 40,000 tokens of raw rows?
Not quite. Return concise, relevant results and offer filters or pagination.
How do you know a tool is well designed?
Not quite. Evaluate by running tasks and reading transcripts.
Two tools, search_orders and find_orders, confuse the model. What is the best fix?
Not quite. Overlapping tools make the model guess. Clear, distinct descriptions help.
You got 0 of 3 right.
Go deeper
- Article
Anthropic · Prototype, evaluate with agents, then iterate.
- Docs
Anthropic · Official guidance on schemas and descriptions.
Spotted a mistake or something unclear? Report it on GitHub.