MCP server dev shares 4 best practices for writing tool descriptions (and test tools)
Mobil_Blood3david177 · reddit · 2026-11-03
A developer building an MCP server for their product shares what they got wrong about tool descriptions and how they fixed it:
- Describe what each tool is for, not how it works under the hood — agents choosing between tools care about when to use one, not which table it hits
- Make similar tools obviously different — two near-identical descriptions caused constant wrong picks
- Put auth and scopes where the agent can see them — keeping them in internal docs made the agent request more access than needed
- Test with real agents, not just the inspector and your own client, using tools like Arcade's ToolBench (scores tool definition quality), Ora (MCP-specific readiness checks), and Netlify's AXIS (agent scenarios, CI-comparable)
The author's server now scores well but remains hard to discover.
More from coding & agent
- Generating isometric sprites locally with fixed-camera 3D renders, no external APIs — chongdashu · 2026-11-03
- Dev shares Claude ACP + Hex + Zed coding stack: 'so satisfying to code and use' — retr0jirachi · 2026-11-03
- Matt Pocock: each agent builds a wiki so you can drop history and switch harnesses freely — mattpocockuk · 2026-11-03
- Matt Pocock shares long-running agent workflow: domain orchestrator thread plus sandboxed software factory — mattpocockuk · 2026-11-03
- Dimillian: Agentic coding at 1,500 PRs a day isn't for intentional game devs — Dimillian · 2026-11-03
- Claude Code can now break down your GitHub Actions minutes across 150 PR runs — one team found half its test jobs missed the dependency cache all year — alex_verem · 2026-11-03