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

Have you ever encountered this situation—

You spend an entire weekend writing an MCP Server, and three tools run perfectly. You throw it to Claude Code, but the AI never calls your tools. Checking the logs, you find it would rather make up answers than touch the interfaces you carefully wrote.

Even more frustrating is the reverse: you tweak a few lines of description hoping the AI will use it more, and the next day you discover it's searching your knowledge base even when saying "good morning" to a user.

This isn't because you can't code. It's because the MCP tool description is written wrong.

When I was writing the knowledge base retrieval tool for kb-builder, I went through three versions. In the first version, the AI almost never called it proactively. After adding trigger scenarios, the trigger rate went up—but it also started searching during small talk and greetings. In the third version, I added three sentences of exclusion boundaries, and the accuracy finally stabilized.

This article is not a documentation translation. It breaks down the iteration process of these three versions into a set of templates you can directly copy.

Tool Descriptions Are Not Documentation, They Are Prompt Engineering

Understand this, and you won't be led astray by a "documentation mindset" when writing the specifics later.

The Tool definition in the MCP protocol has 9 fields (spec version 2025-11-25), but when an LLM selects a tool, only three actually participate in the attention calculation: name, description, and inputSchema. description is injected directly into the system prompt and its similarity to the user query is calculated at the moment of tool selection.

In other words, description is an inference signal fed to the LLM, not API documentation written for humans to read.

Anthropic's engineering team has verified this. When they launched the Claude web search feature, they found the LLM would automatically append "2025" to queries, causing search result bias. In the end, it wasn't fixed by changing the model or the prompt, but by changing the tool description.

This explains a counter-intuitive phenomenon: changing 20 words in the description can have a greater effect than rewriting 200 lines of inputSchema. Because the description controls "whether to select," while the schema controls "how to fill it in after selection." If it's not selected in the first place, no matter how finely written the schema is, it's useless.

A concrete data point: a paper on arxiv this June scanned 19,200 description-code pairs from 2,214 MCP Servers and found that 9.93% had description-code inconsistencies—meaning nearly one in ten Servers had a description saying A, while the actual code did B. Under such descriptions, the AI simply doesn't know what the tool actually does.

With that understood, let's look at how to write specifically.

Three-Part Description Structure: A Template You Can Directly Reuse

Let's start with the conclusion. After three versions of iteration, the description structure I summarized has only three parts:

[A paragraph explaining what this tool does—giving the AI a "map"]
[When to use it—3 to 5 specific trigger scenarios]
[When not to use it—exclusion boundaries]

Taking kb-builder's search_kb tool as an example, the final version of the description looks like this:

Semantically search relevant content in Mage's AI knowledge base. Covers AI programming tools, model comparisons, RAG/Agent/MCP architecture, Prompt engineering, workplace AI efficiency, and backend tech stack: Redis/MySQL/JVM/Kafka/distributed systems/algorithms, etc.

Use this tool when:

• You need to understand the latest practices of an AI technical concept
• You need to compare the pros and cons of AI tools/models
• You need to look up practical experience in backend technology
• You need to find Prompt templates or AI workflows
• You need to cite organized materials when writing technical articles

Do not use this tool when:

• The chat topic is frontend React/Vue/JS knowledge → the knowledge base is mainly backend/AI content
• The user explicitly says "don't search" → do not call
• Pure small talk, greetings → do not call

Below, let's break down section by section why it's written this way, and the common mistakes in each section.

Part 1: One Sentence Clearly Stating What This Tool Does

Many Servers' first paragraph is written like this:

Search the knowledge base for relevant content.

This is a documentation mindset—"I'm telling you what this tool is called and what it does." But the amount of information the AI needs goes far beyond this. When making a tool selection, the AI is matching among 21,000+ available tools. description is its only signal for judging "can this tool solve the user's current problem."

The first paragraph needs to answer three questions: What data/system does this tool operate on? What domains does it cover? What results can it produce?

My initial version only had the first paragraph, and the result was the AI almost never called it. Because it didn't know what was in the knowledge base, it couldn't judge whether the user's question fell within its coverage. When a user asked "What chunk size should I set for RAG," the AI wasn't sure if the knowledge base had RAG-related content, so it simply didn't call it.

After adding the description of covered domains, the AI saw "covers RAG/Agent/MCP architecture" and could make a judgment: the user is asking about RAG, this tool should be able to help.

Don't write "how to use it" in the first paragraph. Parameter details and calling methods go in the inputSchema. The sole task of the first paragraph is to let the AI judge: Is this tool relevant to the user's current intent?

Part 2: Trigger Scenarios Must Be Specific to Actions

This is the most valuable part of the entire description—and the key to my improvement from 30% to 85%+.

In v1.0, my trigger scenarios were written like this:

Use this tool when you need to search.

What's wrong? "When you need to search" is a circular definition—it's as good as saying nothing. The AI doesn't know when it counts as "need to search." A user asks "Is Claude Code any good?" Do you "need to search"? The AI can't judge.

The correct way to write trigger scenarios is specific to actions and context:

• ✅ "When you need to compare the pros and cons of two AI tools"
• ✅ "When you need to cite organized materials while writing a technical article"
• ✅ "When you need to understand the latest practices of an AI technical concept"

Note that these three scenarios are not "different ways of saying the same thing"; they cover three different usage motivations: research comparison, writing citation, and concept lookup. Seeing these three scenarios, the AI can precisely match in the corresponding contexts.

The core principle for writing trigger scenarios: Don't tell the AI "under what circumstances to use it," tell it "what words the user says when you should use it." Put yourself in the AI's role—if your user says "How do I choose between Redis and Kafka for message queuing," would you think you should search the knowledge base? Write this judgment into the description.

Part 3: Exclusion Boundaries Determine the Lower Limit

If Part 2 determines the upper limit of the trigger rate, Part 3 determines the lower limit of trigger quality.

What happens without exclusion boundaries? I stepped into this pitfall. After v2.0 added trigger scenarios, the AI's call frequency went up, but it started calling in completely unrelated contexts—when users were chatting casually, asking frontend questions, or discussing topics completely outside the knowledge base's coverage, the AI would search. This isn't the AI's fault—it was just executing the instructions written in your description: "Use when..."

The way to write exclusion boundaries is precise to the domain and user intent:

• "The chat topic is frontend React/Vue/JS knowledge"—precise to the domain, not a vague "irrelevant topics"
• "The user explicitly says 'don't search'"—precise to user instructions
• "Pure small talk, greetings"—precise to conversational intent

Each of these three lines corresponds to a real user conversation scenario. Seeing them, the AI can lower the weight in these scenarios during attention calculation.

A common objection is: "My knowledge base also has frontend content, why exclude it?"—If your knowledge base indeed has it, don't write the frontend exclusion. Exclusion boundaries are not template fill-ins; they are an honest judgment of your tool's positioning. Every line you write in should be a scenario where you truly don't want the AI to call it.

inputSchema Description: The Severely Underestimated Other Half

Most MCP Server developers put their effort into the tool-level description, casually writing variable names for parameter descriptions. But parameter-level descriptions also participate in LLM reasoning—they take effect during the "parameter filling" stage after tool selection.

A complete inputSchema parameter description should contain four pieces of information:

Parameter name (type): Meaning
  Default value: xxx
  Value range: xxx (e.g., top_k max 15)
  When to change the default: xxx

Taking search_kb's top_k as an example:

top_k (integer): Number of search results returned
  Default value: 5
  Limit: 1-15, automatically truncated if exceeding 15
  When to change the default: Increase to 8-10 when more reference material is needed; decrease to 1-2 when only a precise answer is needed

What's the difference between writing this and just writing "Number of results to return"? When the AI fills in parameters, it doesn't choose values out of thin air—it references the constraints and guidance in the description. Telling it "decrease to 1-2 when only a precise answer is needed" means it will automatically lower top_k for precise questions like "What is the default port for Redis," reducing token waste.

Priority of the four pieces of information: Value range > When to change the default > Meaning > Default value. Because what the AI needs most is "what this parameter cannot be filled with," followed by "what should be filled in different scenarios." Missing the value range description, the AI might fill in values exceeding the limit, causing the tool call to fail.

Write Chinese Descriptions for Chinese Scenarios

If your target users are Chinese-speaking engineers and the knowledge base content is also in Chinese, write the tool descriptions in Chinese.

This is not a language preference issue; it's an attention matching efficiency issue. MCP's tool description and user query are matched in the same semantic space. When a user asks a question in Chinese ("Help me look up the election process of Redis Sentinel mode"), and your description is also in Chinese ("Semantically search relevant content in Mage's AI knowledge base"), the cosine similarity in the embedding space is higher, and the match is more accurate.

Conversely, if your user asks in Chinese but the tool description is written in English, cross-language semantic matching inherently has a loss. The accuracy of cross-language embeddings is still lower than same-language matching, and in the precision-sensitive step of tool selection, this loss is not worth it.

Not all descriptions must be in English. The MCP protocol itself is in English, and it's fine to use English for the name field to ensure compatibility. But for description and the property descriptions in inputSchema, writing in your audience's language yields better matching results.

A counter-example: I've seen a knowledge base MCP Server aimed at Chinese developers, with all descriptions written in English. As a result, when users asked in Chinese "How to configure CORS in Spring Boot," the AI never called it—because the semantic distance between the English description and the Chinese query was too far, and in the ocean of 21,000+ tools, it simply couldn't surface.

If you target international users, you can consider maintaining two sets of descriptions (Chinese and English), but this is a minority scenario. Most MCP Servers have a clear target user base; just write in their language.

Three Tools, Three Non-Overlapping Responsibilities

Returning to the complete practice of kb-builder. I have three tools, and after writing the descriptions clearly, the three have non-overlapping responsibilities, each doing its own job:

search_kb: Use when there is a clear retrieval target. The user has stated specifically what they want to look up. list_kb_topics: Use this first when unsure about the knowledge base's coverage. Equivalent to "check the menu before ordering." get_kb_stats: Use when troubleshooting issues or confirming index status. This is a diagnostic tool, not a query tool.

The division principle for three tools: Each tool corresponds to only one user intent, giving the AI a clear signal to "choose A, not B."

If the description of search_kb also wrote "can view knowledge base statistics," the AI would hesitate when a user asks "What's in the knowledge base"—it has two tools to choose from, and both descriptions match. Overlapping descriptions for multiple tools is like giving the AI a multiple-choice question, increasing the probability of a wrong choice.

When dividing tool responsibilities, ask yourself one question: If the user's intent is described in one sentence, can one and only one tool correspond to it? If not, it means your tool responsibility boundaries need to be redrawn.

💬 How did you write your MCP tool descriptions?

• A. Only wrote the tool name + one-line description, let the AI use it or not
• B. Wrote detailed parameter descriptions, but didn't add trigger scenarios
• C. Have trigger scenarios, but forgot to write exclusion boundaries
• D. Used all three parts, and the results are decent

Tell us your choice in the comments. Mage guesses most people will pick B 😂

FAQ

Q: My tool is generic (e.g., execute_sql), how do I write the three-part structure?

A: The difficulty with generic tools isn't writing the description, but defining the boundaries. The three-part structure is even more necessary: Part 1 clearly states "You can execute arbitrary SQL, but read-only" (if it's a read-only tool); Part 2 lists specific SQL scenarios ("query user info, count orders, compare sales across different time periods"); Part 3 is especially important—"Do not use for creating tables/dropping databases/altering schemas" and other destructive operations. A generic tool without exclusion boundaries is like giving the AI a blank check.

Q: How do I know if my description changes actually improved the results?

A: Logs. Record every tool call: what the user query was, whether the AI called the tool, and whether the call was reasonable (your subjective judgment). After accumulating 50 manual annotations, you have your own eval set. No fancy testing framework needed; a CSV with three columns is enough. The key isn't the tool, but the discipline of continuous recording. Anthropic's engineers also rely on logs to find problems and then change descriptions; they don't get it right the first time either.

Q: When there are many tools, will the descriptions interfere with each other?

A: Yes. The MCP ecosystem currently averages 5-13 tools per Server. When you have more than 8 tools and the descriptions overlap, the AI's selection accuracy drops noticeably. The solution isn't merging tools (a universal tool is worse), but checking the trigger scenarios in each description—if the "Use this tool when" sections of two tools have overlapping use cases, split them into their own unique scenarios.

Q: How long should the description be?

A: The total length of the three-part structure should be controlled within 200-400 characters (about 150-300 words in English). Too short lacks enough information; too long and the AI will truncate it. More exclusion boundaries aren't necessarily better—3-5 are most effective; beyond 7, the AI tends to ignore the later ones. Each property description in inputSchema should be controlled within 20-80 characters.

Ultimately, the Description Reflects Your Understanding of the Tool

After revising the description three times, the biggest takeaway wasn't "mastering a template," but that this template forced me to clearly think through the positioning of each tool—what problem it actually solves, what it doesn't solve, and in what scenarios users will need it.

The root cause of poorly written tool descriptions is often not a writing problem, but that you didn't think clearly about the tool's responsibility boundaries when writing the code. The template just quantifies the fuzziness into concrete sentences—when you get to writing the "when not to use" part, you'll be forced to face those positioning questions you've been avoiding.

The best tool description I've ever seen comes from the beginning of a file operation tool in Anthropic's official reference server: "Read the complete contents of a file from the file system."—No self-praising words like "powerful" or "comprehensive," no extra context, just one sentence clearly stating: read, what, from where.

After writing this, I went back and revised kb-builder's description again. Not kidding.

Next, I plan to break down the parameter design of MCP tools—the gap between well-written and poorly-written inputSchema is even bigger than description. If you're interested, follow so you don't miss it; the algorithm might not push it otherwise. Mage doesn't rely on clickbait for traffic; every article is polished by hand. But this means the algorithm won't actively push it, so star the account, and it'll be there when you want to read. If you have a colleague writing an MCP Server, you can send this article directly to them—saves them from starting with the pitfalls I stepped into.