26 · Writing Better Tools for AI Agents

Great tools make agents reliable, accurate and production-ready. This compares a bad tool to a good tool and gives a cheat sheet for designing tools agents can use correctly.

How it works

1. 1A bad tool (e.g. a vague Search()) leaves the agent confused about inputs and outputs.
2. 2A good tool has clear naming, a strong schema, and is small and focused.
3. 3Define the tool with types and examples (Pydantic/JSON schema).
4. 4Make it idempotent, with predictable output and good error handling.
5. 5The agent then calls it correctly and succeeds.

Key points

• Good tools: clear name, clear description, strong schema, small and focused, idempotent.
• Tool design cheat sheet: purpose, who it's for, inputs, outputs, security, limits, examples.
• The more deterministic and well-described a tool, the more reliably the agent uses it correctly.
• Better tools = smarter agents = more business impact at scale.

Why it matters

Agents are only as good as their tools. Clear, well-typed, well-documented tools are the difference between an agent that works and one that constantly fails.

Frequently asked questions

What makes a good tool?

Clear naming and description, a typed schema, focused scope, idempotency and predictable, well-handled output.

Why does tool description matter?

The model chooses and calls tools from their descriptions — clearer descriptions mean fewer wrong calls.