MCP Tool Description Best Practices
Assistants pick and call tools from their descriptions alone. We read 2,778 tool definitions from 295 public MCP servers to see what good ones do differently.
A good MCP tool description says what the tool does, what it returns, when to use it and when to use a sibling tool instead, and every parameter carries its own description with format and default. In our sample only 14 % of tools say when to use them, 5 % name an alternative, and 15 % of tools with parameters document none of them.
What we measured
We took the 300 servers from our free remote MCP servers picks (one per publisher, 3 to 40 tools, answering without a key) and read their tools/list on 16 October 2026; 295 answered, with 2,778 tools and 8,303 parameters. Only the definitions were read; no tool was called.
| Median description length | 263 characters (10 % under 86, 10 % over 804) |
| Descriptions over 1,000 characters | 185 tools (7 %) |
| Descriptions under 40 characters | 42 tools (1.5 %) |
| Parameters with a description | 6,476 of 8,303 (78 %) |
| Tools with parameters, none described | 352 of 2,393 (15 %) |
| Servers with every parameter described | 164 of 295 (56 %); 51 servers describe fewer than half |
| Tools with annotations | 1,806 (65 %); readOnlyHint on 1,789, destructiveHint on 1,430 |
| Say what they return («returns») | 887 (32 %) |
| Say when to use them («use when», «use this», «when to use») | 376 (14 %) |
| Point to an alternative («instead») | 149 (5 %) |
Directories grade the same things. Glama's tool definition quality score, for example, rates purpose, usage guidelines, behaviour, parameters, conciseness and completeness separately, and an empty parameter description costs points even when the tool itself is clear.
Checklist
- Lead with a verb and the object: «Transcribe the speech of a public video», not «Transcription tool».
- Say what comes back: fields, units, limits. Without an output schema this is the only hint an assistant gets.
- Say when to use it, and when not: «Use get_video_info if you only need the caption». This is what helps an assistant choose between similar tools, and it is the rarest sentence in our sample.
- Describe every parameter in the JSON schema itself: format («'1:05' or seconds»), allowed values (use
enum), default and what happens when it is empty. - State limits and side effects: rate limits, maximum duration or size, whether it writes, spends or sends anything. Mirror that in
readOnlyHint,destructiveHintandopenWorldHint. - Stay short: two to four sentences cover all of the above. A median of 263 characters is about right; 1,000 and more usually repeats itself and costs every user context.
- Add a title for humans (
titleorannotations.title) so clients can show «Transcribe video» instead oftranscribe_video.
Before and after
One of our own tools before the rewrite, graded C by Glama (2.9 out of 5):
creator_monetization
"Sourced 2026 data on creator monetization: platform programs and requirements,
YouTube/TikTok RPM by niche or country, engagement-rate benchmarks, sponsored post rates."
parameters: topic (enum), platform, niche, country (no descriptions)After:
"Look up sourced 2026 creator-income data. topic=programs lists monetization programs with
eligibility (subscribers, watch hours, views) and status; rpm_by_niche and rpm_by_country give
earnings per 1,000 views as low, high and median; engagement_benchmarks gives typical engagement
rates; sponsorship_rates gives price ranges per post. Every row carries its sources. Use it to
answer 'how much does X pay' or 'what do I need to monetize'; for a concrete earnings estimate
from a view count use estimate_youtube_earnings instead. Offline data, max 40 rows."
topic: "Which table to read." (enum, default programs)
platform: "Optional platform filter, substring: YouTube, TikTok, Instagram ..."
niche: "Optional niche filter for rpm_by_niche and sponsorship_rates ..."
country: "Optional country filter for rpm_by_country: ISO code (US, DE, IN) or English name."Result: Glama re-scored the tool a few hours after the rewrite, from 2.9 to 4.8 out of 5 on its tool definition quality score. The other eight tools of the server, rewritten the same way, now score between 4.1 and 4.9.
Check your own server: the MCP Server Tester lists every tool and counts how many parameters are described.
How it works
- Lead with what it does Verb plus object, then what it returns.
- Say when to use it And which sibling tool to use instead.
- Describe every parameter Format, allowed values, default, inside the JSON schema.
FAQ
How long should an MCP tool description be?
Two to four sentences. In our sample of 2,778 tools the median was 263 characters; 7 % ran past 1,000 characters, which usually repeats itself and costs context on every request.
Do MCP tool parameters need descriptions?
Yes. Assistants fill parameters from the schema, and directories grade it. In our sample 15 % of tools with parameters described none of them.
What should an MCP tool description contain?
What the tool does, what it returns, when to use it and when to use another tool instead, limits such as rate or size, and whether it changes anything.
Which MCP tool annotations should I set?
readOnlyHint, destructiveHint, idempotentHint and openWorldHint describe behaviour; title gives a human-readable name. 65 % of the tools we read set at least one annotation.