Designing Tools Your Agent Can Actually Use
An agent is only as good as its tools. Naming, schemas, error messages, and output size matter more than the framework you pick.
When an agent misbehaves, the instinct is to tweak the system prompt. More often the problem is the tool surface. The model only knows what your tool names, descriptions, and results tell it.
Write descriptions for a new teammate
A tool description is documentation for a reader with zero context. Say what the tool does, when to use it, when **not** to use it, and what the parameters mean. One clear paragraph beats a terse one-liner.
Make the schema hard to misuse
- Prefer enums over free-form strings when there's a fixed set of options.
- Use explicit units in parameter names: `timeout_seconds`, not `timeout`.
- Turn on strict schema validation so malformed calls fail fast instead of running.
Return errors the model can act on
`Error 500` teaches nothing. `"No customer with id 'c_123'. Use search_customers to find the right id."` tells the agent exactly how to recover. Return failures as tool results marked as errors rather than throwing them away; the model will usually fix the call on its next turn.
Keep outputs small
Every token a tool returns is context the model has to carry for the rest of the run. Paginate, truncate with a note ("showing 20 of 340, pass `page=2` for more"), and return IDs plus summaries instead of whole records.
Fewer, better tools
Ten overlapping tools force the model to choose between near-duplicates. Consolidate them: one `search_orders` with filters beats `get_orders_by_date`, `get_orders_by_customer`, and `get_orders_by_status`.
Test the tools, not just the agent
Run each tool against realistic inputs and read the results as if you were the model. If you'd be confused, so will it.
Newsletter
Get new posts by email
Practical notes on AI agents and system architecture. No spam, unsubscribe anytime.