Blog
#0135 min read

Tools for AI agents: design them as if for someone new on the team

Tools are how an AI agent acts on your systems, and the part that changes its results the most. How to choose them, name them, describe them and make them hard to misuse.

When an AI agent fails, the first thing people check is the prompt. Often the problem is somewhere else: in the tools you gave it. A tool with an ambiguous name, a one-line description or a ten-thousand-row response confuses a model the same way it would confuse someone new on your team.

Anthropic sums it up in an idea I like: your tools are the interface between the agent and your system, and they deserve the same care as an interface for people (Building effective agents). In their research system, rewriting the tool descriptions alone cut task completion time by 40% (How we built our multi-agent research system).

This is the second note in the series on how to build AI agents. Here are the rules I follow, most of them from Anthropic’s guide to agent tools (Writing effective tools for agents, 2025).

Few tools, built for the job

The most common mistake is wrapping every endpoint of your API in a tool. The agent ends up with forty similar options and picks the wrong one. More tools don’t give better results.

The alternative is to design a few tools that each do a complete job:

  • Instead of list_contacts, which returns all of them, a search_contacts tool that returns the ones that matter.
  • Instead of separate check_availability and create_event tools, one book_appointment that checks the calendar and books in a single step.
  • Instead of three calls to build a customer’s history, one get_customer that returns what a support rep would want to see.

A good test: if a person on your team would never do that step on its own, the agent shouldn’t have to either.

Names that can’t be confused

When there are tools from several systems, group them with a prefix per service and resource: crm_search_customers, crm_get_customer, calendar_search_slots. The agent chooses better when the name already says where the tool comes from and what it acts on.

The same goes for parameters. customer_id beats customer, because it leaves no doubt about whether it expects a name, an email or a number.

Descriptions written for someone new

A tool’s description is part of the prompt. Write it the way you’d explain it to someone who joined the team yesterday: what it does, when to use it, what each term means and what format the data comes in.

vague-tool.json
{
"name": "appointments",
"description": "Manages appointments.",
"input_schema": {
"type": "object",
"properties": { "date": { "type": "string" }, "id": { "type": "string" } }
}
}
clear-tool.json
{
"name": "calendar_search_slots",
"description": "Finds open slots for a service within a date range. Use it before offering the customer a time. It books nothing: to book, use calendar_book_appointment.",
"input_schema": {
"type": "object",
"properties": {
"service_id": { "type": "string", "description": "The service ID, taken from calendar_list_services. E.g. 'srv_cleaning'." },
"from": { "type": "string", "format": "date", "description": "First day to search, as YYYY-MM-DD." },
"to": { "type": "string", "format": "date", "description": "Last day to search. At most 14 days after 'from'." }
},
"required": ["service_id", "from", "to"]
}
}

The second one says when to use it, what it doesn’t do and where each value comes from. With that, the model stops guessing.

Make it hard to misuse

Anthropic borrows a term from Japanese manufacturing: poka-yoke, designing something so the mistake is hard to make. In their case, the agent kept getting relative file paths wrong, so they changed the tool to accept only absolute paths, and the error went away.

In a business, it looks like this:

  • Dates in a fixed format, not “Tuesday”.
  • Closed lists (enum) when there are only a few valid options, instead of free text.
  • Amounts in a numeric field with their currency, not “about 200 grand”.
  • For risky actions, a separate confirmation step that your system checks, not the model.

Every constraint you put in the tool is a failure you don’t have to catch later.

Responses the agent can use

Whatever a tool returns goes, in full, into the agent’s context. So:

  • Return what matters. Readable names and statuses, not just internal identifiers. If the agent needs an ID for the next call, include it next to the name.
  • Watch the size. Pagination, filters and a default limit. Claude Code, for example, truncates tool responses at 25,000 tokens by default. A huge response doesn’t just cost more: it pushes what the agent needed to remember out of focus.
  • Offer levels of detail. A parameter like format: "concise" | "detailed" lets the agent choose how much it needs.

Errors that say what to do

An error that says 400 Bad Request teaches the agent nothing. One that says what went wrong and how to fix it does:

errors.txt
Bad: Error 400
Good: The date "11/4" isn't in YYYY-MM-DD format. Use, for example, "2026-11-04".
Good: There are no open slots for that service between those dates. Try a wider range
or offer the customer a person to talk to.

A good error message is the difference between an agent that recovers on its own and one that repeats the same call five times.

The tool bench: a few well-labeled tools, and the agent picks the right one at each step.

Test them on real tasks

Tools are designed with data, not intuition. Put together a set of real, multi-step tasks with an outcome you can verify, and watch how the agent uses your tools: how many calls it makes, which ones fail, which ones it ignores and how many tokens it spends. Read the transcripts. That’s where you find the tool the agent mixes up with another, or the parameter it never gets right.

The full method is in how to evaluate an AI agent.