Why do 97% of MCP tool descriptions fail — and is fixing them actually worth it?

Is the problem with your MCP tools the code — or the words you used to describe them?

Researchers who asked exactly that question published two peer-reviewed studies in early 2026, and the answer surprised most people following the MCP ecosystem closely. Across a sample of 856 tools from 103 production MCP servers, 97.1% of tool descriptions contained at least one quality problem serious enough to affect AI agent performance. When the same research group examined 10,831 servers to check whether that was a sampling fluke, they found the same pattern playing out at scale.

This is not an abstract concern. A separate study of 177,436 MCP tools tracked over 16 months found that action tools — the ones that actually modify external environments, send messages, edit files, or trigger transactions — grew from 27% of the ecosystem to 65%. The quality of your tool descriptions determines whether AI agents call those tools correctly, call the wrong ones, or miss them entirely.

Where do these numbers come from?

Both quality studies appeared on arXiv in early 2026. The first, "Model Context Protocol (MCP) Tool Descriptions Are Smelly!" (arXiv 2602.14878), borrowed a concept from software engineering — code smells, the structural patterns that make code harder to maintain — and applied it to tool descriptions. Researchers built a rubric, audited 856 tools from 103 real production servers, and then ran controlled experiments to measure how description quality affected actual agent task completion. The second paper, "From Docs to Descriptions: Smell-Aware Evaluation of MCP Server Descriptions" (arXiv 2602.18914), applied a related framework to a much larger dataset of 10,831 servers and quantified the statistical effect on LLM tool selection accuracy.

Neither study used synthetic data. Both worked entirely with publicly available MCP servers.

How much does description quality actually matter?

The numbers are starker than most people expect. When AI agents select from a pool of MCP tools at random — the zero-information baseline — they pick the right tool about 20% of the time. When tool descriptions meet documented quality standards, that rises to 72%. A 260% improvement, achieved purely by writing better text.

The implication: most of the tools published today are not performing at 72% selection accuracy. They are performing somewhere between the random baseline and that ceiling, depending on how well their descriptions communicate intent.

What does a bad description actually look like?

Across the 10,831 servers in the larger study, three problems showed up most often. Repeated tool names — where two or more tools in the same server share a name or are described in nearly identical terms — affected 73% of all servers. That one causes the most obvious failures: the agent calls the wrong tool because the descriptions give it no basis to distinguish between them. A server with both a search tool and a search_records tool is setting up an agent to guess, and sometimes it will guess wrong.

Wrong parameter semantics, present in 31.8% of servers, is subtler. A parameter named user_id might actually expect an email address. A field called limit might have an undocumented ceiling of 50 that silently truncates results without an error. An agent providing plausible-but-wrong inputs gets unpredictable behavior with no obvious explanation.

Missing return value descriptions, in 28.6% of servers, leaves agents in the dark about what to do after a tool call completes. If your tool returns {"status": "ok", "ref": "a1b2c3"} and the description does not say what ref is, the agent cannot decide whether to chain another call, surface the value to the user, or just move on.

The researchers flagged something worth sitting with here: there was no statistically significant difference in description quality between official MCP servers published by large software vendors and community-built servers. Both groups showed similar rates of description smells. The pattern they labelled "code-first, description-last" does not discriminate by team size or company reputation.

The first paper drilled further into the 856-tool sample and identified six quality components that matter: purpose clarity, usage guidelines, stated limitations, parameter explanation, description length, and concrete examples. Across all six, 97.1% of tool descriptions failed at least one.

Does fixing the descriptions actually help — and at what cost?

The short answer is yes, with a catch.

When researchers from the first study augmented tool descriptions to fix identified smells — adding clear purpose statements, explaining what parameters actually contain, documenting return values — task success rates improved by a median of 5.85 percentage points and partial goal completion went up 15.12%. Those are meaningful gains on real agent benchmarks.

But augmenting descriptions also increased the number of execution steps by 67.46%. Richer descriptions give AI agents more text to process before each decision, which translates into more reasoning steps before the agent reaches a conclusion. And in 16.67% of test cases, augmented descriptions actually made performance worse — likely because the added context introduced competing interpretations or raised the agent's uncertainty.

So the recommendation is not simply "add more words to every description." Fixing specific, concrete problems — duplicate tool names, wrong parameter semantics, missing return documentation — delivers near-pure gains. Padding descriptions with comprehensive prose is a different bet with real overhead and a meaningful regression risk.

Why does this keep happening?

Because most developers build MCP tools the same way they build any internal function: get it working, handle the edge cases, add a brief docstring if there is time. That workflow is fine when your API consumers are other developers who can read source code, run the function with test inputs, and ask questions on Slack when something breaks.

AI agents cannot do any of that. They read the description once, at inference time, and make a decision. A tool named process that accepts an options object is workable for a human developer with access to the repository. For an agent mid-task, it is essentially opaque.

The protocol itself does not enforce description quality. MCP tool descriptions are free-text strings. No validator rejects a one-word description, no linter flags duplicate names, no required schema field forces you to document what the tool returns. Quality is entirely voluntary — which is how 97.1% of tools end up with at least one problem.

What should site owners actually do?

A few things that come directly from the research findings:

Name your tools so they cannot be confused with each other. The 73% repeated-names figure is the most common problem and the most avoidable. If two tools in the same server could plausibly be confused, rename at least one. search_by_keyword and search_semantically are distinguishable; search and advanced_search are not, especially when an agent is reasoning under time pressure.

Document what parameters actually contain, not just what they are named. If date_from expects a Unix timestamp in milliseconds rather than an ISO 8601 string, say so explicitly. If count has a hard ceiling, state it. These are the "unstated limitations" flagged most often in the 856-tool study, and they are among the cheapest problems to fix.

Specify what the tool returns. If your tool returns an array of objects with specific fields, name those fields. An agent that understands the return structure can chain tool calls correctly; one that does not will guess and occasionally chain incorrectly in ways that are difficult to debug.

Resist the urge to over-document. The 67.46% increase in execution steps from heavily augmented descriptions is real overhead — more steps means more time and more inference cost. Precision matters more than volume. A short, accurate description of exactly what the tool does and what it requires is more useful than three paragraphs of caveats.

A practical test: read your tool description as if you were a competent developer who has never seen your codebase, has no documentation to reference, and has 30 seconds to decide whether to call this tool or pick a different one. That is the position an AI agent is in every time it evaluates your server.