MCP · AI Coding · Agent

A 20-Word Description Change Lifted MCP Tool Accuracy to 85%

By 码哥字节 · Jul 31, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Tool-call accuracy is the difference between an agent that silently hallucinates answers and one that actually uses your APIs. A small, disciplined change to description text — not model retraining or prompt overhauls — fixes the selection problem at the root, and the same template works across any MCP Server.

Summary

Most MCP Server developers treat tool descriptions as documentation for humans, but the LLM uses only three fields — name, description, and inputSchema — during tool selection. A description is an inference signal injected into the system prompt; changing 20 words can matter more than rewriting 200 lines of schema. Nearly 10% of MCP Servers scanned in a recent paper had description-code mismatches, so the AI never learns what the tool actually does. The fix is a three-part description template: a one-sentence domain map, 3–5 specific trigger scenarios phrased as user utterances, and 3–5 exclusion boundaries that prevent calls during small talk or out-of-scope topics. Parameter-level descriptions in inputSchema need the same care — value ranges and guidance on when to change defaults stop the model from filling impossible values or wasting tokens. For Chinese-speaking users, descriptions written in Chinese match queries more accurately in the embedding space than English descriptions do.

Takeaways

— Only three MCP Tool fields — name, description, and inputSchema — participate in the LLM's attention calculation during tool selection.

— 9.93% of 19,200 description-code pairs across 2,214 MCP Servers contain inconsistencies where the description says one thing and the code does another.

— A three-part description structure — what the tool does, when to use it (3–5 concrete user-utterance scenarios), and when not to use it (3–5 exclusion boundaries) — raised trigger accuracy from near zero to over 85%.

— Exclusion boundaries should be precise to domain and user intent (e.g., 'chat topic is frontend React/Vue/JS') rather than vague ('irrelevant topics').

— inputSchema parameter descriptions need four pieces of information: meaning, default value, value range, and when to change the default — with value range being the highest priority.

— Writing tool descriptions in the same language as the target user's queries produces higher cosine similarity in the embedding space and more accurate tool matching.

— Tools with overlapping trigger scenarios force the LLM into a multiple-choice problem; each tool should map to exactly one user intent.

— Logging 50 manually annotated query-tool-call pairs in a simple CSV is sufficient to evaluate description changes without a dedicated testing framework.

Conclusions

The counter-intuitive finding that 20 words of description outweigh 200 lines of schema follows directly from the MCP protocol's architecture: description controls selection, schema controls parameter filling, and a tool that is never selected gets no benefit from a perfect schema.

Writing trigger scenarios as literal user utterances ('when the user asks to compare two AI tools') rather than abstract conditions ('when comparison is needed') shifts the description from documentation to prompt engineering — it gives the LLM a direct pattern to match against the query.

The 9.93% description-code mismatch rate suggests a systemic failure mode: developers update code without updating descriptions, creating tools that the LLM can never learn to use correctly because the signal it receives is factually wrong.

Exclusion boundaries are not just a safety net; they are a precision control. Without them, higher trigger rates degrade into noise because the LLM follows the positive instruction literally across all contexts, including greetings and off-topic chat.

Language choice in descriptions is an embedding-space optimization problem, not a stylistic preference — cross-language semantic matching still carries a measurable accuracy penalty that matters at tool-selection time among 21,000+ competing tools.

Concepts & terms

MCP Tool description as inference signal

In the Model Context Protocol, a tool's description field is injected directly into the LLM's system prompt and used during attention calculation to determine whether the tool matches the user's query. It functions as a prompt-engineering lever, not as human-facing documentation.

Three-part description template

A reusable structure for MCP tool descriptions: (1) a one-sentence domain map stating what data/system the tool operates on and what it covers, (2) 3–5 trigger scenarios written as concrete user utterances, and (3) 3–5 exclusion boundaries specifying domains or intents where the tool should not be called.

inputSchema parameter description priority

For each parameter in an MCP tool's inputSchema, four pieces of information should be provided in order of importance: value range (what the parameter cannot be), when to change the default, meaning, and default value. Missing value-range descriptions can cause the LLM to fill impossible values and fail the tool call.

Description-code inconsistency

A mismatch where an MCP Server's tool description states one behavior but the actual implementation does another. A June 2025 arxiv paper found this in 9.93% of 19,200 description-code pairs, making it impossible for the LLM to learn the tool's true function.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗