The State of MCP Tool Design

An MCP server is not an API, and the difference is the whole story. An API is read once by a developer at integration time, with the docs open and a colleague to ask. A tool manifest is read by a model on every single request, with no memory of last time, no documentation, and no way to ask a clarifying question before it commits to a call.

Anything ambiguous in that manifest does not produce an error. It produces a confident, plausible, wrong call — which is a far more expensive failure, because nothing alerts on it.

97% of live servers we measured carry at least one finding that costs tokens, accuracy, or both. Five were clean.

How the corpus scored

Most servers are mediocre, not broken

The median server scores 83 — a B. That is the finding, and it is easy to misread. The problem is not a field full of disasters. It is a field where the default outcome is “works well enough that nobody investigates,” while quietly paying for it on every request.

A 46 · 26%

B 66 · 38%

C 38 · 22%

D 14 · 8%

F 12 · 7%

What goes wrong

The same six mistakes, everywhere

The failures are strikingly uniform. These are not exotic bugs — they are defaults nobody revisited, and every one of them is a half-day fix.

Failure mode	Servers affected
No guidance on failure behaviour When a call fails the model cannot tell whether to retry, adjust, or stop. It usually retries with variations, burns tokens, then answers confidently from nothing.	64%
No required parameters declared If everything is optional, nothing signals which arguments make the call meaningful. Models sometimes call with none at all.	61%
Zero tool annotations Without readOnlyHint and destructiveHint, a client cannot separate a safe read from an irreversible write. Hosts then prompt on everything, training users to click through.	53%
Descriptions never state what comes back Without a stated return shape the model cannot plan a second step, so it calls the tool speculatively just to discover what it returns.	43%
Parameters with no description The model infers intent from the parameter name alone. This is the single most common source of malformed calls.	34%
Constrained values typed as open strings A missing enum turns a choice into a guess. The model supplies something reasonable-sounding, the API rejects it, and the retry loop begins.	29%
List tools with no pagination control An unbounded result can exceed the remaining context, truncating the conversation and destroying earlier state — one of the most common ways a working integration falls over in production.	22%
Destructive tools not marked destructive Names implying deletion, refunds, or outbound messages, with nothing in the manifest telling a client to confirm first.	16%

The part nobody measures

Every manifest is a standing bill

Tool definitions are serialised into context on every request, whether or not the tool is ever called. That makes manifest size a recurring cost paid across every user, every turn, forever — and it is almost never anybody's line item.

The spread is severe. The median manifest is modest. The top of the distribution is not.

Median manifest

1,994

tokens per request — entirely reasonable

90th percentile

10,318

5× the median, before any user message

Largest measured

89,254

one server, 301 tools, on every single request

That server's annual tax

~$98k

at 1,000 requests/day and $3/Mtok input

The largest manifest in the corpus exposes 301 distinct tools. Well before that point, a model is not selecting a tool so much as picking one out of a haystack, and when it picks wrong the call still succeeds — it just answers a question nobody asked.

Median tool count across the corpus is 7. The 90th percentile is 26. The gap between those numbers is where most of the damage lives.

Method

Every server in the public MCP registry was enumerated (19,008 unique entries, of which 9,189 advertise a remote endpoint). Reachable servers were queried with a single tools/list call over streamable HTTP. No other traffic was sent, no authenticated endpoints were accessed, and no server was called more than once. 176 returned a manifest; the remainder required credentials, had moved, or did not respond.

Each manifest was scored against six weighted dimensions — context cost, tool surface, naming, descriptions, schema clarity, and safety semantics. Individual results are not published here. Companies are being contacted with their own findings directly.

Limitations, stated plainly

This is static analysis. It measures properties of the manifest that are known to correlate with agent failure. It does not execute tasks, so it does not measure real task success rate. A server can score well and still perform poorly.
Token counts are estimates, calibrated for JSON at roughly ±15%. Good enough to rank and to decide what to trim; not good enough to invoice against.
The sample is biased toward the reachable. Servers behind authentication — disproportionately the larger commercial ones — are absent. Since tool count correlates with nearly every failure mode here, the true picture is likely somewhat worse than these numbers, not better.
The rubric is opinionated, and reasonable engineers will disagree with parts of it. Where it is wrong we would like to know, and it will be corrected.

None of this is anybody's fault

Nearly every pattern in this report was encouraged by the tooling. Generating a manifest from an existing API specification produces exactly these results: one tool per endpoint, the summary line as the description, parameters carried across untouched, no annotations, no pagination contract. It is the path of least resistance and it was the sensible thing to do at the time.

The fixes are unglamorous and mostly mechanical. Describe the parameters. Declare what is required. Add the enum. Say what comes back. Mark the destructive ones destructive. Put a limit on the lists. None of it is hard. It has simply not been anyone's job yet.