The Problem
The model selects tools based on their descriptions, but most MCP server authors write descriptions for humans, not models. Too vague and the model picks the wrong tool. Too verbose and you waste context on a single schema. The quality of tool descriptions directly determines tool selection accuracy.
Good vs Bad Descriptions
// Bad: vague, human-oriented
"description": "Search for stuff"
// Bad: too verbose
"description": "This tool allows you
to search our comprehensive database
of customer records including..."
// 200 tokens of description
// Good: precise, model-oriented
"description": "Search customer records
by name, email, or account ID.
Returns top 10 matches with
contact info and account status."
Open Problems
Tool overlap: Two different MCP servers might offer similar capabilities (two search tools, two file readers). Without deduplication or preference logic, the model picks arbitrarily.
No versioning: When an MCP server updates its tool schemas, the agent has no way to know. Stale descriptions in cache cause silent failures.
No quality standard: MCP standardizes the interface but not description quality, schema conventions, or documentation depth.
Rule of thumb: Write tool descriptions as if you’re explaining the tool to a new engineer who needs to decide when to use it. Include: what it does, what inputs it needs, what it returns, and when to use it vs. alternatives.