Checklist for Writing Agent Tool Descriptions
Hot-Leadership-6431 · reddit · 2026-07-13
The author argues that many agent failures aren't due to poor reasoning, but because tool descriptions are written for humans, leaving the agent clueless about when to use or avoid them.
They provide a checklist for rewriting tool descriptions:
- Describe the tool's purpose in one sentence, avoiding internal jargon
- Specify applicable and non-applicable scenarios
- Clarify input fields, formats, and provide examples
- Detail the return structure upon failure for easier recovery
- Explain side effects and whether the action is reversible
The author also suggests a simple test: give the tool list to someone unfamiliar with the system and ask them to select tools for sample requests; if a human hesitates, the agent will too. The empirical conclusion is that fewer, highly refined tools with clear boundaries work better for agents than a clutter of overlapping ones.
More from coding & agent
- HeyGen adds a media-sourcing skill for coding agents with 75k images and 10k tracks — HeyGen · 2026-07-22
- Agent search bottlenecks are now about variance, not raw latency — rohanpaul_ai · 2026-07-22
- LangSmith adds tracing for Pipecat, LiveKit, OpenAI Realtime, and Gemini Live — LangChain · 2026-07-22
- An MCP server signs every AI agent tool call into a verifiable Merkle chain — Funky_Chicken_22 · 2026-07-22
- Annotated transcript of a Claude Code team interview is now available — trq212 · 2026-07-22
- Claude Code skill uses 10 Markdown rules to make outputs ADHD-friendly — alex_verem · 2026-07-22