Three tools, three clear descriptions — a small tool belt done well beats a large one done vaguely.
1Small and Clear Beats Large and Vague
TriageAgent needs exactly three capabilities for its actual job: finding relevant policy text, checking a ticket's real state, and escalating it. Adding tools 'just in case' — beyond what the task genuinely requires — gives the model more chances to pick the wrong one and adds no real capability the agent will use.
2The Description Is the Actual API Surface
This is the same lesson from designing MCP tool schemas, applied to a hand-rolled ReAct agent instead of a formal protocol: the model reasoning about which tool to call has nothing to go on except the name and description you give it. A vague description like 'handles docs' gives it far less to reason from than 'search internal docs for a relevant policy or troubleshooting step.'
3Step-by-Step Breakdown
TriageAgent's Real Tool Belt. TriageAgent needs exactly three real capabilities: search_docs to find a relevant policy, get_ticket to check a ticket's real details, and escalate_ticket to actually hand it off. Every tool needs a clear description, because — same as any tool-using system — the model deciding when to use one only ever sees that description, never your code.
Build the Real Tool Prompt. The three tools are already defined, each with a real description. Finish build_tool_prompt so it actually assembles those descriptions into the text block the agent hands the model at the start of every run.
Why does build_tool_prompt include each tool's description, not just its bare name, in the text handed to the model?
- →The description is the model's only signal for what a tool does and when it's appropriate to use it — it never sees the implementation behind the name.
- →It's purely for visual formatting and has no effect on which tool the model picks.
Module 1 Complete: A Real Reasoning Agent. TriageAgent can now loop, execute real tools, and reason from real descriptions of what those tools do. It's still missing memory and real retrieval, though — right now every run starts from zero context. Next module: giving it both.
Level Up 🚀
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
Fully supported.
Fully supported.
Fully supported.
Fully supported.
Accessibility (A11y)
1List Available Tools Explicitly in Any Agent Trace UI
A UI displaying an agent's run should list which tools were available for that step, not only which one was chosen — helping a user understand why a different tool wasn't picked.
<span>Available: search_docs, get_ticket, escalate_ticket</span>SEO Implications
- 1
Target 'AI agent tool belt design' and 'agent tool description best practices' separately
Developers scoping their first agent search for the overall design question and the specific description-writing practice independently.
Best Practices
Write Tool Descriptions the Way You'd Explain the Tool to a New Teammate
A description clear enough for a human colleague unfamiliar with your codebase to understand when to use the tool tends to be clear enough for a model reasoning about the same decision.
Frequent Bugs
Giving two tools overlapping descriptions that could both plausibly apply to the same situation.
Ambiguous overlap between tool descriptions increases the chance the model picks the less appropriate one — keep each tool's description specific enough to distinguish it clearly from the others.
Real-World Examples
Overloaded Tool Belts
An agent given a dozen loosely-related tools with thin one-line descriptions measurably selects the wrong one more often than the same agent given three narrow, clearly-described tools scoped to its actual job.
# Prefer 3 clear tools over 12 vague ones