Writing MCP tool descriptions the model actually understands
An MCP tool description is your user interface. What it must contain, the mistakes that come up every time, and the test that exposes ambiguity.
An MCP tool description is not documentation. It is your user interface.
It is the only thing the model reads before deciding whether to call your tool, and it is often what the end user sees too. A vague description produces exactly the same effect as a badly labelled button: nobody clicks, or everybody clicks at the wrong moment.
The base rule
A description has to answer three questions, in this order:
- What does this tool do
- When should it be used rather than another
- What does it not do
Most servers only answer the first. The second determines selection, and the third prevents absurd calls.
Before and after
Before: "Retrieves a list of items."
That says nothing about what an item is, when this tool is the right one, or how it differs from the three others that also retrieve lists.
After: "Lists the user's forms, drafts and published. Use it to find an existing form before editing it or reading its responses. Does not return response contents."
We gained the scope, the moment of use and the limit. Three sentences, and it changes the selection rate.
The mistakes that come up every time
Writing for a developer. "Performs a GET on /api/v2/items with pagination" means nothing to the model, which is not calling your API but your tool.
Restating the tool name. "create_form: creates a form." That is a wasted line.
Forgetting the parameters. Every parameter also has a description in the schema. An undescribed parameter will be filled by guesswork, often badly. Defaults and expected formats belong there.
Putting infrastructure in it. Internal hostnames, tenant identifiers, paths. The description is read by the model and often visible.
Treating error messages as a detail. They are part of the interface. A clear error lets the model correct itself. A raw database error makes it loop, and leaks your schema.
Your users' vocabulary, not yours
This is the highest-return and most neglected point.
Your users do not ask to "instantiate an entity of type form". They say "make me a satisfaction questionnaire". If the word "questionnaire" appears nowhere in your descriptions, the match happens less reliably.
Simple procedure: take twenty real user requests, note the nouns they use, and check those words appear in your descriptions.
Annotations matter as much as the text
A tool can be annotated as read-only or destructive. That is not decorative.
It is what lets the client require human confirmation before an irreversible action. Without annotations, all your tools look alike, and an agent will treat deletion like a read.
Annotate systematically. It costs one line and it changes how your server is perceived, including in a directory submission.
The test
Give your tool list, names and descriptions only, to someone who does not know your product. Ask them, for ten requests phrased in natural language, which tool they would pick.
Wherever a human hesitates, the model will get it wrong. And the human can tell you why.
FAQ
How long should they be?
Two to four sentences for the tool, one line per non-obvious parameter. Longer does not improve selection and burns context.
Should descriptions include examples?
A short example helps on ambiguous formats, like dates or identifiers. Not needed elsewhere.
Should I translate my descriptions?
Keep one consistent language. The model bridges to the user's language.
Get your tool surface reviewed
The audit includes a review of names, descriptions, parameters, annotations and error messages, with a selection test on real requests. Within 24 business hours.
Ready to check? Get my MCP server audited →
Related reading
Got an MCP server to audit?
Five minutes to describe it. I reply within one business day with a first written diagnosis, free of charge.
Get my MCP server audited