Designing Tools Agents Actually Want to Use
MCP made tool plumbing standard. Good tool design is still rare — and it is the difference between an agent that finishes and one that flails.
Model Context Protocol standardized how tools are described and called. That solved the wiring problem. It did not solve the harder problem: describing tools so clearly that a model picks the right one, calls it correctly, and knows when to stop.
Names and descriptions are the API
The model has no memory of your codebase. Its entire understanding of a tool is the name, the description, and the parameter schema. If those are vague, the model guesses — and guesses wrong at scale.
- Name tools as verb_noun: create_issue, search_docs, refund_payment.
- State when to use and when not to use, not just what it does.
- Constrain parameters with enums and formats, not free strings, wherever possible.
Fewer, composable tools beat many overlapping ones
Three tools the model calls reliably beat ten tools it confuses. If two tools overlap, merge them behind a parameter, or hide one behind the other. Decision cost scales with the menu size.
// bad: two tools, ambiguous choice
{ name: "list_open_issues" }
{ name: "list_closed_issues" }
// better: one tool, one parameter
{ name: "list_issues", params: { state: "open|closed" } }
Return what the model needs next
Tool output should hand the model its next decision, not raw data it must parse. Return summarised, structured results with clear next-step hints. A tool that dumps 500 rows is a tool that produces bad next turns.
The tool description is the prompt. Write it like a prompt, not like a docstring.
