Your Agent Is Guessing What Your Tool Parameters Mean

When your agent calls an MCP tool, it has never seen your code. It sees three things: the tool's name, the tool's description, and the JSON schema of its parameters. From that text alone it has to decide which tool to call and how to fill every argument. So when a parameter has no description, the agent doesn't fail loudly — it guesses. And guessing is where agents quietly go wrong: the wrong path, a malformed filter, an argument in the wrong format.

Everyone says "write good tool descriptions." We wanted the receipts. So we connected to the eight official Model Context Protocol reference servers, pulled their real tool schemas over the wire (tools/list), and measured the documentation — no model in the loop, just counting. The headline:

43% of all 224 parameters across the official MCP servers have no description at all.

And it's worse where it hurts most.

The most-installed servers are the worst documented

tooldoc — documentation audit of 8 MCP server(s)

  [D]  git                  12 tools · 28 params   79% of params undocumented
  [D]  filesystem           14 tools · 25 params   72% of params undocumented
  [C]  memory                9 tools ·  8 params   50% of params undocumented
  [C]  github               26 tools · 130 params  39% of params undocumented
  [A]  everything           13 tools · 16 params    6% of params undocumented
  [A]  fetch                 1 tool  ·  4 params    0% of params undocumented
  [A]  time                  2 tools ·  4 params    0% of params undocumented
  [A]  sequentialthinking    1 tool  ·  9 params    0% of params undocumented

  ● 43% of all 224 parameters across these servers have no description.

The filesystem and git servers — two of the most commonly installed MCP servers on the planet — leave 72% and 79% of their tool parameters undocumented. (That 72% is not a coincidence: a number that's been floating around unsourced is "72% of parameters on Anthropic's MCP servers have no descriptions." We re-measured it from scratch against the live servers, and filesystem lands on it exactly.)

Here's the part that makes it concrete. The agent calling filesystem sees this for its single most-used tool:

{ "name": "read_file",
  "description": "Read the complete contents of a file…",
  "inputSchema": { "properties": {
    "path": { "type": "string" },          // ← no description
    "head": { "type": "number", "description": "…first N lines" },
    "tail": { "type": "number", "description": "…last N lines" } } } }

head and tail are documented. path — the one argument that actually matters — is a bare string. Relative or absolute? Relative to what? The agent guesses. Same story on github: create_issue.owner, .repo, .title, .body are all free-form strings with no descriptions; the model infers what goes in each from the field name and hopes.

The gap is parameters, not tools

The cleanest finding from the audit is where the debt lives. Every single tool across all eight servers has a description. Tool-level docs are fine. The entire 43% is at the parameter level — the layer people stop documenting because the name "looks obvious." It looks obvious to you. The model, which fills it blind, gets the U-shaped end of "lost in translation."

This lines up with the broader research: a 2026 study found 97.1% of MCP tool descriptions carry at least one quality issue, and that fixing them measurably lifts task success. Teams are already responding by deleting tools to cope — GitHub cut Copilot's MCP surface 40→13, Block trimmed a Linear server from 30+ tools to 2. But you can't tell a well-documented tool from a guess-magnet by counting tools. You have to read the schemas.

tooldoc

So that's what tooldoc does. Point it at a .mcp.json, an ad-hoc server, or a captured tools/list, and it grades the documentation:

tooldoc                              # connects to your servers
tooldoc --server "npx -y @scope/srv"
tooldoc --tools captured.json
tooldoc --min-grade B                # fail CI if any server is worse than B

It measures the things that make a model guess:

• Tools with no description, or a one-word description (which tool do I pick?).
• Parameters with no description — the dominant signal, weighted heaviest in the grade.
• Free-form string parameters with no description and no enum — maximally guess-prone; there's nothing for the model to anchor on. (tooldoc lists them by name: read_file.path, git_diff.target, …)
• Name collisions — the same tool name exposed by two servers, so the model has to disambiguate shadowed tools.

Each server gets an A–F grade weighted on parameter coverage, and there's a corpus-wide number when you audit several. --min-grade turns it into a CI gate: if you ship an MCP server, fail the build when a tool's parameters go undocumented, the same way you'd fail on a lint error.

A note on honesty: this is a documentation audit, deliberately separate from the token-cost audit we wrote about before. A short description isn't automatically bad and a long one isn't automatically good — tooldoc flags absence (no description, no enum on a free-form string), which is unambiguous, and leaves "is this description any good" to your judgment. The grade is a heuristic; the underlying counts are exact and recomputable. Every number in this post you can reproduce by running the tool against the public servers yourself.

If you build MCP servers, document the parameters

The fix is unglamorous and cheap: give every parameter a one-line description, and give every free-form string an example or an enum if it has a fixed set of values. path → "Absolute path to the file, or relative to the server's root directory." That one sentence is the difference between the agent reading the right file and the agent reading ./path. You spent real effort exposing the tool; the description is what the model actually runs on.

And if you just use MCP servers: run tooldoc on your stack before you add the next one. A server that's 79% undocumented isn't giving your agent twelve clean tools — it's giving it twelve invitations to guess.

tooldoc is a single file, no dependencies — point it at your servers and see the grades. → Talk to us if you're building or wrangling MCP tools.

---

Prior art credited: the "97.1% have quality issues" study (arxiv 2602.14878) and the tool-overload write-ups motivated this; tooldoc's contribution is the deterministic, per-server measurement on the real official corpus plus a runnable grade you can put in CI. It audits documentation quality, not token cost (that's a separate tool). Counts are exact; grades are heuristic.

---

Get the tool → tooldoc in agent-ops — open source (MIT), a single dependency-free script, part of our toolkit for running coding agents in production.