Writing Effective Tools for AI Agents

The process it recommends

Tool design is treated as an iterative engineering loop rather than a one-off:

1. Prototype quickly and try the tools locally with a real agent.
2. Run an evaluation built from realistic, multi-step tasks. Track accuracy, runtime, number of tool calls, token use and errors.
3. Improve with an agent's help. Feed the evaluation transcripts to a coding agent, let it suggest changes to tool descriptions and implementations, and check the result on a held-out set so you do not overfit.

The article contrasts weak and strong evaluation tasks. A weak one tells the agent exactly what to search for. A strong one describes a real problem (a customer charged three times for one purchase) and leaves the agent to work out which tools to use.

Five principles for the tools themselves

• Build fewer, higher-impact tools. Do not wrap every API endpoint. A single schedule_event tool beats separate tools to list users, list events and create an event, because it matches how the task is actually done.
• Namespace related tools with clear prefixes so the agent can tell similar tools apart.
• Return meaningful context. Prefer human-readable names over opaque IDs, and drop fields the agent will not use. Optionally offer a concise and a detailed response format.
• Be token-efficient. Add pagination, filtering and truncation with sensible defaults, and make error messages tell the agent how to fix its call rather than returning a bare code.
• Prompt-engineer the descriptions. Write them as you would for a new teammate, spelling out what inputs mean and what comes back. Small wording changes can produce large improvements.

How to apply it

• Take one tool your agent misuses and read the transcript of a failure. Usually the description is ambiguous or the output is too large.
• Rewrite the description with explicit parameter meanings and an example.
• Cut the response down to what the next step needs.
• Build ten realistic evaluation tasks before adding more tools, so you can tell whether a change helped.

Where it fits

It is the practical companion to Building Effective Agents (which covers overall architecture) and Effective Context Engineering (which covers what goes into the model's context). Reading all three gives a solid, vendor-neutral foundation for agent work, even if you use models from other providers.

Common questions

Does this apply if I use OpenAI or Gemini function calling? Yes. The principles are about how any model reads tool definitions and results.

How many tools is too many? There is no fixed number. The test is whether the agent reliably picks the right one; if it confuses similar tools, merge or namespace them.

Do I really need evaluations for a small project? Even ten realistic tasks, run before and after a change, will tell you more than trying one example by hand.

Best for: developers writing MCP servers, function-calling schemas or internal tools for agents.