Tool descriptions for AI agents are the part of an MCP server that most people knock out in ten seconds. One sentence, done, on to the interesting ...
For further actions, you may consider blocking this person and/or reporting abuse
The point that the model only ever sees name + description + schema, never the code, is the one I wish more MCP authors internalized — the description is prompt, competing for attention with every other tool.
In practice the failure we hit most isn't vagueness, it's overlap. When two tools could each plausibly serve a request, the model disambiguates on surface wording and picks wrong surprisingly often. The fix that moved our numbers was writing descriptions that say when not to reach for a tool and name the sibling it's confused with ("use X for a single record; for bulk, use Y"). Negative space turned out to matter more than richer positive description.
Your error-messages-as-recovery-path section deserves top billing too. An error that states the fix ("expected ISO-8601, received 10/28/2026") recovers in one turn; a generic "invalid input" sends the model into a retry loop that burns tokens and sometimes gives up. Does your CI check catch semantic overlap between two tools, or mainly weak single descriptions? Overlap is the one that's hard to lint for.
Agreed – naming the sibling tool ('for bulk, use Y') is one of the cheapest fixes. Thanks for sharing what actually moved your numbers.
The overlapping tools pitfall is the one I hit most with MCP servers. Two descriptions that read alike make the model pick the wrong tool, and the error message is where recovery actually happens. A CI check that flags near-duplicate descriptions is cheaper than debugging an agent transcript after the fact.
Nice idea – a CI check for near-duplicate descriptions catches the overlap before an agent ever sees it.
Letting the model pick concise or detailed through responseFormat is a neat touch, since every result lands in the context window whether the next step needs it or not. Readable ids like bike-hafen-01 help the same way, because the model can carry them into the next call without another lookup.
Thanks! Readable IDs are underrated – they save the model a lookup and make transcripts much easier to debug.
Writing the description like you're onboarding a new colleague is how a good scope of work reads too: what's included, what isn't, and what to do when the job doesn't match the drawings. The bug your test caught, where the code didn't keep the description's promise, is the gap we care most about at ML Systems.
Thanks! The scope-of-work comparison fits well – especially the part about what isn't included.
One thing to check on the host side: on the hosted MCP server I measured, the Store description goes out verbatim after a one-line preamble, and long field descriptions are cut somewhere around 370 to 500 characters with a truncation marker. So the sentence that decides the pick should sit in the first 300 or so.
Embed each description and flag pairs above 0.9 similarity. That catches the drift before a new tool ships.
Most teams skip the last step. A tool description is a prompt, so check it like one: run the agent on a few real tasks and count the wrong picks. Eight rules are a guess until that count exists.
Fair point – the rules are a starting hypothesis. Running a few real tasks and counting wrong tool picks is what tells you whether a description change actually helped.