How to write MCP tool descriptions (we graded 7,660 of them)

On 2 November 2026 we ran our tool-description grader over every tool we have on file: 7,660 tools from 673 MCP servers. The median description is seven words long. Two thirds are under ten words. Thirty-six of them just repeat the tool's own name.

A description is most of what a model has when it decides whether to call your tool and what to put in the arguments. The MCP spec itself calls it a hint to the model. So it matters that so many of them say close to nothing. This post covers what we found, what published research says about it, and seven changes that are cheap to make.

What we measured, and what we didn't

Every server page in the directory has a tools tab, and each tool on it gets a score out of 100 and a letter from A to F. The six checks are on the methodology page: does it have a description, is the length sensible, does it open with an action verb, are the inputs documented, are side effects explained for tools that write, and is there any usage guidance.

Some limits to know before you read the numbers.

• Most of these descriptions come from READMEs and registry metadata, not from a live tools/list call. They are what a person sees when reading the docs. They are usually what the server sends too, but we can't promise that.
• The extractor keeps at most 40 tools per server and clips each description to 240 characters, roughly 40 words. That clips the long end, so we only draw conclusions about the short end, where clipping can't hide anything.
• We have no input schemas for these tools, so the inputs check falls back to looking for phrases like "by id" or "takes a path" in the text. It is the least reliable of the six.
• README extraction is messy. A few rows are table cells holding a bare checkmark, and a few "tools" are really parameters.
• The grader counts Latin-alphabet words. Thirty descriptions are in Chinese, Japanese or Korean and 29 of them got an F, which says more about the grader than about the descriptions.
• The verb list is finite. "Ensure ssh-agent is running" loses the verb points because "ensure" isn't on it.
• This is a small slice of the directory. The "has declared tools" filter lists 694 servers out of 47,703. Paging through it we reached 677 distinct servers (the order shifts a little while you page), and 673 of those list at least one tool.

So treat a single grade as a pointer, and the shape of the whole distribution as the finding.

What 7,660 descriptions look like

Tool description grades across 673 servers, 2 November 2026. Source: the tools pages in the MCPpedia directory.

The average score is 52 out of 100. Of 7,660 tools, 412 earn an A (5.4%), 1,082 a B (14.1%), 2,129 a C (27.8%), 2,116 a D (27.6%) and 1,921 an F (25.1%). About one tool in five gets a B or better.

Length is where the pattern is clearest.

• 192 tools (2.5%) have no description at all, and 84 more hold only symbols or non-Latin text.
• 2,336 (30.5%) have between one and four words.
• 2,475 (32.3%) have five to nine.
• In total, 66% are under ten words, and the median is seven.
• 36 descriptions are the tool name restated, for example list_projects described as "List projects".

Only 54 tools, 0.7%, score a perfect 100. They come from 23 servers. Here are two of them, both from servers we list. The first is dropbox_create_folder:

Create a new folder in Dropbox at a specified path. Returns folder metadata. Use to organize files or set up directory structures.

The second is confluence_list_spaces:

List all Confluence spaces in your instance. Returns space ID, key, name, type, and status. Use to discover documentation areas.

Neither is long. Each says what it does, names what comes back, and says when to reach for it. That is most of the job. You can see both on the Dropbox and Confluence server pages.

Two more numbers, and both come with the caveat that the heuristics behind them are blunt:

• 1,567 tools look like they write, send or delete something, judging by their name or opening verb. Only 132 of those, about 8%, say what changes or whether it can be undone.
• Names are consistent. 94% are snake_case (7,197 of 7,660), and get is the first word of 1,125 tools (14.7%), ahead of list (445), search (176), create (166), update (96) and delete (88). That also means a lot of generic names. 265 tool names appear on more than one server.

What the research says

There is not much published work on this yet, and most of it is preprints, so read the numbers as early evidence.

A February 2026 preprint, Model Context Protocol (MCP) Tool Descriptions Are Smelly, scored 856 tools from 103 servers on six components such as purpose, usage guidance, limitations and parameter explanation. It found 97.1% had at least one weakness. When the authors rewrote descriptions to fix all of them, task success rose by a median of 5.85 percentage points. The same rewrite raised the median number of execution steps by 67.46%, and 16.67% of cases got worse. Their ablation found shorter, targeted descriptions could match the fully rewritten ones. The agent runs used GPT-4.1 and three open models, not Claude.

A second preprint, From Docs to Descriptions, looked at 10,831 servers. It reports that 73% of them reuse a tool name that other servers also use. In a controlled setup where a model chose between tools, a tool with a well-written functional description was picked 17.8% of the time against 6.2% with none (10% would be chance). The authors say clearly that this setup is artificial, so don't read it as a general lift.

Vendors give more concrete advice than the spec does. The spec defines the fields and says nothing about length or wording. Anthropic's tool-use docs say detailed descriptions are the biggest factor in tool performance and suggest at least three or four sentences. Its engineering post Writing effective tools for agents says to describe a tool the way you would for a new hire. OpenAI's function-calling guide leans toward fewer tools and sparing examples. Those pull in slightly different directions, and the rewrite study above suggests that more words aren't automatically better.

Seven changes worth making

The examples below are invented, to show the shape of each fix. They are not from any listed server.

1. Say what comes back

A name tells the model what the tool is about. Only the description can say what the call returns.

Before: Search issues.
After:  Search issues in one repository by keyword, label or assignee.
        Returns up to 20 results with number, title, state and URL,
        newest first. Read-only.

2. Name each input and say where its value comes from

user could be a name, an email or an id. The model will guess.

Before: {"user": {"type": "string"}}
After:  {"user_id": {"type": "string",
         "description": "Numeric id from users_search, for example 48213."}}

If you publish a schema, use enums for fixed choices and mark required fields. If your host only reads the README, put the same detail there.

3. Say what changes, and set the annotations

For any tool that writes, sends or deletes, the description should say what is changed and whether it can be undone. Then set the annotations. The spec's defaults describe a tool with no annotations as not read-only, possibly destructive and open-world, so a harmless lookup that sets nothing looks riskier than it is.

Before: Delete a label.
After:  Permanently delete a label from a repository and remove it from
        every issue that uses it. Cannot be undone.
        (destructiveHint: true, readOnlyHint: false)

The spec also tells clients to treat annotations as untrusted unless they come from a trusted server. They are hints, so the description still has to carry the facts.

4. Say when to use it, and what to use instead

If two tools overlap, the model needs a tie-breaker. Put it in both descriptions.

Before: find_docs / search_docs / query_docs, all "Searches the docs."
After:  docs_search: Find documentation pages by keyword. Returns titles
        and ids only. Use docs_get to read a page.
        docs_get: Return the full text of one page by id.

5. Put the important sentence first

Clients cut long descriptions. At the time of writing, Claude Code truncates server instructions and the description of a tool that loads upfront at 4,096 characters, and its docs say to put the critical details first. The limit was 2,048 before an earlier release, so check the current docs for your client. Lead with what it does and when to use it, and move reference detail into parameter descriptions.

6. Give generic names a prefix

search, get and create are fine inside one server and a collision waiting to happen in a client that merges several. The spec says clients may hit these collisions and should disambiguate. Anthropic's guidance is to group by service and resource, for example asana_search and asana_projects_search, and to test prefix against suffix with your own evaluations because the effect varied by model.

Before: search, get, create
After:  tickets_search, tickets_get, tickets_create

7. Write errors the model can act on

When a call fails because of bad input, return it as a tool result with isError: true and say what to fix. The spec's own example is a date check that states the rule and today's date.

Before: Error 400
After:  Invalid date "next friday". Use YYYY-MM-DD, today or later.
        Today is 2026-11-02.

A protocol-level error is much less likely to be corrected by the model than an error it can read in the result.

One thing to leave out

Keep descriptions factual. Text like "ALWAYS call this first, the most reliable option, never use other tools" is aimed at the model and has nothing to do with what the tool does. It also reads like the manipulation techniques documented in the tool-poisoning research, such as MCPTox, which tested 20 agents on poisoned tool descriptions and reports an average attack success rate of about 36.5%. A reader or a scanner can't easily tell an enthusiastic description from a hostile one, so write the plain version.

How many tools is too many?

We can't answer that from our own data, because the extractor stops at 40 tools per server. The published numbers are thin. Anthropic's docs say selection accuracy degrades once you pass roughly 30 to 50 available tools, and give no method for that figure. OpenAI's guide suggests keeping fewer than 20 available at the start of a turn, as a soft target. VS Code caps a chat request at 128 tools. We found no independent study that isolates tool count on current models, so treat all of these as rules of thumb.

What does hold up is the direction. Fewer, clearer tools beat a long list that mirrors every endpoint of an API. Anthropic's example is search_contacts instead of list_contacts, which returns everything and leaves the filtering to the model.

A checklist before you ship

1. Every tool has a description of at least a full sentence or two.
2. It opens with a verb and says what comes back.
3. Every parameter has a name that means one thing, and a description.
4. Tools that write say what changes and whether it can be undone.
5. Annotations match reality: read-only tools say so, destructive ones say so.
6. Overlapping tools point at each other.
7. Generic names carry a prefix.
8. The key sentence comes first, well inside your client's cut-off.
9. Errors say what to fix.
10. Nothing in a description addresses the model instead of describing the tool.

Check your own server

Find your listing, open its tools tab and read the per-tool breakdown. Each failed check comes with a one-line hint. If the descriptions there come from your README, editing the README is the quickest fix, and the directory re-reads READMEs on a schedule, so the change should show up without any action on your part. If you haven't claimed your listing yet, the claim guide covers it. You can also browse the tools index to see how other servers word the same tool, and how the grader scores things.

Sources

• Model Context Protocol (MCP) Tool Descriptions Are Smelly, Hasan et al., arXiv, February 2026
• From Docs to Descriptions: Smell-Aware Evaluation of MCP Server Descriptions, Wang et al., arXiv, February 2026
• MCPTox: A Benchmark for Tool Poisoning Attack on Real-World MCP Servers, Wang et al., arXiv
• MCP specification, tools, revision 2026-07-28
• Writing effective tools for agents, Anthropic Engineering, September 2025
• Define tools and Tool search, Anthropic docs
• Claude Code MCP documentation
• Function calling guide, OpenAI
• Chat tools in VS Code