vvek

Designing tools an AI agent can use well: fewer tools, clearer names, smaller answers

Practical rules for agent tools, drawn from Anthropic's engineering guide: consolidate, name clearly, return readable and short results, and test with real tasks.

When an agent does something silly, the first instinct is to blame the model or rewrite the prompt. Often the real problem is the tools. The agent was handed twenty near-identical functions, vague names and answers the size of a phone book, and it did what anyone would do in that situation: it guessed.

Anthropic published a detailed engineering guide on writing tools for agents. This post turns its main points into a checklist you can apply to your own tools this week, whatever model or framework you use.

A tool is a contract with a reader that has no memory

A normal function is called by a programmer who read the docs once and remembers them. An agent tool is called by a model that sees only the name, the description and the parameter list, fresh, every time. It can't ask a colleague what process_item really does.

So write each tool as you would explain it to a new hire. State what it does, when to use it, what the inputs mean and what the output looks like. Spell out the niche terms your team takes for granted.

Fewer, better tools

The tempting move is to wrap every endpoint of an existing API. The guide advises against it: build a few tools for the workflows that matter, check they work, then grow.

Consolidation is the biggest lever. If a task always needs "find the person, check their calendar, create the event", give the agent one scheduling tool rather than three small ones it has to chain correctly. Each extra step is another place to go wrong, and another description competing for attention.

Tip

A good test: could a person decide, from the tool list alone, which tool to use for a given job? If two tools make you hesitate, the model will hesitate too. Merge them, or make their purposes clearly different.

Names that help the model choose

When you have many tools, group them with a shared prefix by service or resource, for example crm_contacts_search and crm_deals_search. The guide notes that prefix or suffix style can change how well agents pick tools, so try both against your own tasks rather than assuming.

Parameters deserve the same care. user_id says more than user. A parameter that accepts "a date" invites trouble; say "date as YYYY-MM-DD".

Return what a reader needs, not what the database has

This is where many tools go wrong. A database row full of internal ids, timestamps and flags is cheap to return and expensive to read. Prefer:

  • Names and titles over opaque identifiers, with the id included only if a later call needs it.
  • A response_format option such as concise and detailed, so the agent can start small and ask for more. In the guide's Slack example, concise answers used about a third of the tokens.
  • Pagination, filters and sensible defaults, so "list everything" is never the easy path.
  • Truncation with a clear note about what was cut. The guide mentions that Claude Code limits tool responses to 25,000 tokens by default.

Everything a tool returns goes into the model's context, and context is a budget. We wrote about why in Context engineering for agents: give the model less, but better.

{
  "tool": "crm_contacts_search",
  "input": { "query": "Priya Nair", "response_format": "concise", "limit": 5 }
}

A concise answer here might be five lines of name, company and email. The detailed form, with notes and history, is one more call away if the agent needs it.

Errors should teach

An error such as E4032 helps nobody. An error such as "No contact matched 'Priya Nair'. Try searching by company, or check spelling" gives the agent a next move. Treat error and truncation messages as instructions, because the model will read them that way.

Check the tools against real work

You can't judge a tool by reading it. The guide's evaluation method is simple to follow:

  1. Write a set of realistic tasks, including some that need many tool calls. "Schedule a meeting with Priya next week and attach the latest proposal" beats "call the search tool".
  2. Give each task a way to check the outcome, one that ignores harmless differences such as wording or formatting.
  3. Run each task through a plain agent loop and record accuracy, run time, number of tool calls, tokens used and errors.
  4. Read the transcripts. An agent that takes eight calls for a two-call job is telling you your tools are confusing, even if it got the right answer.
  5. Keep some tasks aside as a held-out set, so you don't tune the tools to your own examples.

If you have not built an evaluation set yet, Evals for AI agents: start with twenty tasks, grade the outcome walks through the first afternoon.

Tools are also where safety lives

Everything above is about being useful. One more point belongs on the list: the tool is the right place to limit what an agent can do. Narrow inputs, read-only variants and approval for risky actions are all easier to enforce in the tool than in the prompt. See Giving an AI agent only the access it needs for that side.

A quick review you can do today

Take your current tool list and ask, for each tool:

  • Does it have one clear purpose that differs from every other tool?
  • Would a new colleague understand the description without asking?
  • Are parameter names unambiguous?
  • Does the default response fit comfortably in a few hundred tokens?
  • Do the errors say what to try next?
  • Have you seen it used in a real transcript?

Fix the worst offender first, rerun your tasks, and compare. Small changes to descriptions and responses often move results more than any prompt rewrite.

Sources

Keep reading

A short email when we publish. Confirm once, unsubscribe any time.