- In short
- MCP tool description enhancement is the practice of rewriting a tool description so an agent reliably chooses the MCP tool over a built-in alternative. Because Claude selects tools from their descriptions, a vague MCP description loses to a familiar built-in like Grep, while a description that states the tool advantage and use cases wins the selection.
Why an MCP tool description decides everything
An MCP tool description is not documentation that sits quietly beside the tool; it is the input the model reads when it decides which tool to call. Claude selects tools by matching the task in front of it against the descriptions of the tools available, so the description is the single most influential thing about whether your tool gets used. This knowledge point is rated apply because the exam expects you to take a tool that is being ignored and rewrite its description so the agent starts choosing it.
The failure this addresses is specific and common. You install or build a capable MCP server, the tools are right there in the agent's toolset, and yet the agent keeps reaching for a built-in like Grep instead. The reason is not that the MCP tool is worse; it is that the agent has strong, familiar built-in tools and a vague MCP description gives it no reason to deviate from the familiar path. The model defaults to what it knows unless the description makes a clear case for the alternative.
- Tool description enhancement
- Rewriting an MCP tool's description so an agent reliably selects it over a built-in alternative, by stating the tool's purpose, the situations where it is superior, and the concrete advantage it offers.
The built-in competition problem
To enhance a description well, you have to understand what it is competing against. Claude Code ships with capable built-in tools, and the model has deep familiarity with common patterns from its training. That familiarity is a gravitational pull: faced with a search task, the agent gravitates toward the built-in search it knows rather than an unfamiliar MCP tool described in one bland sentence. A weak description does not lose because it is wrong; it loses because it never makes the case that this tool is the better choice for this kind of task.
This reframes description writing as a selection problem, not a labeling one. The job is not merely to say what the tool is. The job is to give the model a reason to prefer it precisely in the moments where it would otherwise fall back to a built-in. That is why this KP is distinct from general tool-description writing: it is specifically about winning a head-to-head against a default the agent already trusts.
How to enhance an MCP tool description
A strong enhanced description does three jobs that a weak one skips.
- State the purpose unambiguously. Say plainly what the tool does, in concrete terms, without assuming the reader shares your context. Anthropic's guidance is to write a tool description the way you would explain it to a new teammate, making explicit the specialized formats, niche terminology, and resource relationships you would otherwise leave implicit.
- Name the situations where it wins. Spell out the cases where this tool is the right choice over the alternatives. If your code-search MCP tool understands semantic structure that a literal text search misses, say so and give the kind of query where that matters.
- State the advantage over the built-in. Make the comparison explicit. The model is weighing your tool against a built-in it already likes, so tell it the edge: more accurate results, fewer tokens, structured output, awareness of project context the built-in lacks.
Clear parameter naming reinforces all three. A parameter called user_id instead of a bare user removes ambiguity at the moment of the call, and even small refinements like this can produce outsized improvements in how reliably the agent uses the tool correctly.
The anatomy of a strong description
It helps to have a shape in mind so you are not writing from a blank page. A strong enhanced description tends to move through the same beats: a plain statement of what the tool does, a sentence or two on the situations where it is the right call, an explicit note of the advantage it holds over the obvious alternative, and clear parameters whose names say what they expect. You do not need a rigid template, but you do need every one of those beats present, because each one answers a question the model is implicitly asking when it decides whether to call your tool: what is this, when would I use it, why would I prefer it, and what do I pass it.
The discipline that ties the beats together is the new-teammate test. Imagine briefing someone capable who simply lacks your context, and make explicit the things you would otherwise assume: the specialized formats, the niche terms, the relationships between the underlying resources. The description that passes that test is almost always the one that wins the selection, because the model, like the new teammate, can only act on what you actually said.
Parameters, naming, and namespacing
Description quality does not stop at the prose; the parameter names are part of the signal. A parameter called user_id tells the model far more than a bare user, and that small specificity removes ambiguity at the exact moment of the call, which can yield a disproportionate improvement in how reliably the tool is used. When an agent has access to many tools across several servers, namespacing helps too: grouping related tools under a common prefix, organized by service or resource type, gives the model clearer boundaries and reduces confusion about which tool belongs to which system. Anthropic's guidance even notes that the choice between prefix and suffix namespacing produces measurable differences, which is the clearest possible signal that naming is worth testing rather than guessing.
How much description is enough
There is a concrete bar for length, not just a vibe. Anthropic calls the description "by far the most important factor in tool performance" and recommends a minimum of three to four sentences for any non-trivial tool. Those sentences should cover what the tool does, when to use it, when not to use it, what each parameter means, and any caveats or limitations. The when-not-to-use clause is the one teams skip, and it is often exactly what keeps the agent from grabbing the MCP tool for a task a built-in handles better, which is the same selection problem this knowledge point exists to solve.
The tool definition also gives you levers beyond prose. Optional input_examples let you attach valid example input objects, so the model can see how the tool is called rather than only read about it, which helps most for parameters with non-obvious shapes. On the API side, marking a tool strict: true makes Claude's calls conform exactly to the input schema, trading a little flexibility for far fewer malformed calls. Even the name carries signal and is constrained to the pattern ^[a-zA-Z0-9_-]{1,64}$, so a clear, valid identifier is part of what the model reads.
None of this replaces the new-teammate test; it sharpens it. Three or four honest sentences, a concrete example input, and a strict schema give the model both the reasoning and the exact shape it needs, and that combination is often what tips a close decision toward your tool instead of the familiar built-in it would otherwise default to.
Iterate empirically, and know what to leave out
Because descriptions drive a probabilistic selection, the reliable way to improve them is to measure, not to theorize. Change a description, run the agent against representative tasks, and watch whether selection improves; treat the wording as something you tune against evidence rather than settle once. It is just as important to know what to leave out. A description is not a place for implementation detail the model does not need, for cryptic identifiers where a human-readable label would do, or for vague filler that adds length without adding a reason to choose the tool. Keep it high-signal: every sentence should either clarify what the tool does or strengthen the case for selecting it. Anything that does neither is dilution, and dilution is how a description quietly slides back toward being ignored.
Where it fits in the integration story
Description enhancement is the last mile of an MCP integration and the natural successor to the build-versus-use decision. A custom server you built to fill a real gap is wasted if the agent never calls it, and even an adopted community server often ships with descriptions tuned for breadth rather than for winning against Claude's specific built-ins. So whichever path the build-versus-use decision took, this is the step that converts a configured tool into a used one. It is also the leg that integration best practices flag as the most commonly skipped, which is exactly why it gets its own knowledge point.
Why it matters for the exam
A scenario for this topic describes a capable MCP tool that is available but unused, with the agent stubbornly preferring a built-in. The exam wants you to identify the lever, the description, and the remedy, enhancing it to state purpose, preferred situations, and advantage. The trap answers reach for blunt instruments: forcing tool choice, removing the built-in, or adding more tools. Those either fight the symptom or make things worse, while the description fix addresses the actual cause, which is that the model was never given a reason to choose the better tool.
Worked example
A team builds a semantic code-search MCP tool that understands their codebase structure. It is far better than plain text search for their needs, but agents keep using the built-in Grep and ignoring it. The current description reads simply: search the codebase.
Start by naming why the tool loses. The description, search the codebase, is exactly the territory the built-in Grep already owns in the model's mind. Read that line during a search task and the model sees no daylight between the MCP tool and the familiar built-in, so it picks the one it trusts. Nothing about the sentence argues for the MCP tool, so the capable tool sits unused.
Now enhance the description against the three jobs. Purpose, made specific: the tool performs semantic code search that resolves symbols and follows references across files, rather than matching literal text. When to prefer it: use it for questions like where is this function actually used or what calls this API, where a literal text match returns noise or misses indirect references. Advantage over the built-in: it returns structurally relevant results with far less irrelevant output than a raw text grep, so the agent spends fewer tokens sifting matches. Tighten the parameters too, so a query argument is named for what it expects rather than left generic.
Re-read the enhanced description as the model would during a where-is-this-used task. Now there is a clear reason to deviate from the built-in: the description explicitly claims the situations and the edge that fit the task at hand. The agent selects the semantic tool, and the capability the team built finally gets used. Notice the fix touched only the description. You did not force tool choice, delete Grep, or add tools; you gave the model the reason to choose well that it was missing.
Common misreadings to avoid
Misconception
If an MCP tool is more capable than the built-in, the agent will recognize that and use it regardless of how it is described.
What's actually true
Misconception
The way to make Claude use an ignored MCP tool is to force tool choice or remove the competing built-in.
What's actually true
How it shows up on the exam
A team's custom MCP tool retrieves authoritative, up-to-date data from their internal system, but agents keep answering from memory or using a built-in tool instead of calling it. The MCP tool's description is a single vague line. What is the most effective fix?
People also ask
Why does Claude ignore my MCP tool?
How do I make Claude use an MCP tool instead of Grep?
What makes a good MCP tool description?
Can a tool description change which tool Claude picks?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
Defining tools with MCP
Why watch: Writing strong MCP tool descriptions so agents prefer them over weaker built-ins is exactly this enhancement KP.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.