Tool descriptions are prompts — write them like it

It calls the wrong tool, so you write a rule about it

So we shipped the server, and now, for example, it chooses another tool when you ask it to use the notes tool, or it calls it with an argument that doesn't make sense, or it never touches it at all, so you'd create a line in the memory file like "if they ask about the last incident, point them to the notes server". The thing is, the memory file isn't the right layer, it's too meta and far from the choice itself. The description field of the tool that it needs to choose between in a situation where there are multiple similarly-named search tools is what it's all about

Anthropic says without any reservations that detailed descriptions are the most important thing in terms of how well a tool works. But if you put in the description the most reasonable docstring in the world, it's one line long, present tense, and addressed to a human who has the repo open — what the model sees under the hood is the tool name, that one sentence, parameter names, and parameter descriptions. So let's look at what it actually sees:

What actually reaches the model

• MCP:

  • definition for every tool: name (required), title (optional), description, icons array (optional), inputSchema (required), outputSchema (optional), annotations (optional)

  • the display label is set in the title, which is optional, while the description is what the model actually reasons over, so you need to be mindful of it and write good prose for the sake of the description field; the title you put there is written for a sidebar

• The client:

  • If we were to run a server with two tools against a harness and ask the model "what can you see without calling anything?" — it'd tell us that it can see mcp__notes__notes_search and mcp__notes__search, and the descriptions of both would be identical to what we've put in there (for the second tool we made the description a single word on purpose). So it namespaces the names, and the prose itself gets there intact

  • The official filesystem server v2026.7.10 ships with 14 tools, definitions are 13635 characters long, which is 3400 tokens (4 characters per token) — all this before the first request

Descriptions are the biggest part of it with 4108 characters, compared to 3274 for schemas and 203 for names

The name is doing more work than you think

But names carry more weight than we think. We all assume that the name is just a handle, so whatever is important must be in the description — but people who measure say the opposite. In this r/mcp thread from August 2025, someone says:

We found out that surprisingly that tool names matter a ton; and with a good tool name, you don't need a long description

And when someone pushed back, they went further:

What was surprising was that tool names >> tool descriptions. We had many situations where fixing the name was the key instead of adding more to the description

And another commenter says:

there is functionally no barrier between the function name, the parameters, and the description. it's all just a chunk of text

Which is an important point; there's no separation between the function name, parameters, and description — it's all just a block of text.

So let's look at some examples:

The first one is from a post by the edgar.tools maintainer from June 2026. At that point they had 27 tools already in production, and the names of their tools were created side by side for each category like this:

search_companies
search_funds
search_advisers

fund_profile
adviser_profile

So after the first two, the model can predict the third one. They go on to say:

Eight tools with blurry boundaries route worse than 27 that form a grammar

What they're saying is that it wasn't about how many tools you have — if you have eight tools with unclear boundaries, they'll route worse than 27 tools that have a consistent naming pattern.

And the second example is from the same post:

search_companies
search_funds
search_advisers

fund_profile
adviser_profile

search_entities

They merged three searches into one search_entities tool with an additional type parameter, and then watched the traffic. In the same window, the abstract search_entities was called 15 times by six users, while the concrete search_companies was called 173 times by 37 users.

They say:

Models match the user's noun ('find the company'), not your type hierarchy

And the Docker server maintainer from this very thread has done something similar — they split a vague manage_container tool with an action parameter into four tools:

start_container
stop_container
restart_container
get_container_logs

It's the same functionality, but much better routing.

So it's not a controlled experiment, but if you have figures for how well it works, you can't ignore it. And these two do beat some of the rules of thumb because they attach numbers to it. It's also worth noting that:

• MCP spec says that tool names can be 1–128 characters long and should consist of ASCII letters, digits, underscore, hyphen, dot

• The Messages API from Anthropic has a similar limit, but more restrictive — ^[a-zA-Z0-9_-]{1,64}$, so letters, digits, underscore and hyphen, up to 64 characters, no dots

So you can use letters, digits, underscore, and hyphen, but keep it short because the client might prepend something on its own. We've even seen a dot surviving the trip, although it got converted into an underscore — the model saw admin.tools.list as mcp__notes__admin_tools_list. So admin.tools.list and admin_tools_list collapse onto the same visible name.

And when we tried to send a 60-character-long name with a 12-character-long prefix, it arrived in full at 72 characters, so no truncation in this version, but definitely not worth the hassle

Four questions the description has to answer

Now, let's have a look at what your description should say. Anthropic frames it as if you were to describe a tool to a new joiner, and you need to put there all the things you'd naturally assume they know so that you don't need to tell them about. Like what types of queries the tool supports, how some specific terms are defined in the context of this tool, or what are the relationships between different entities it operates on.

So it should answer four questions:

1. What does it do? — a single clause, verb and object

2. When to use it and when not to — we'll get back to that

3. What format each parameter is in — not type

4. What it doesn't return and what it can't see

Let's have a look at this before/after comparison of the same notes-search tool definition:

{
  "name": "search",
  "description": "Search.",
  "inputSchema": {
    "type": "object",
    "properties": { "q": { "type": "string" } },
    "required": ["q"]
  }
}

{
  "name": "notes_search",
  "title": "Search engineering notes",
  "description": "Full-text search over the team's engineering notes: postmortems, RFCs and on-call handovers, from 2023 onward. Use it when the question is about a decision the team already made or an incident it already had. It does not read the codebase and does not see anything filed under `drafts/`. Returns at most 20 matches, newest first, each with its title, date and the matching paragraph.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Words to match, not a question. 'redis eviction', not 'why did we change redis eviction'."
      },
      "since": {
        "type": "string",
        "description": "Oldest note to consider, as YYYY-MM-DD. Defaults to one year ago."
      }
    },
    "required": ["query"]
  }
}

So we increased the name to a specific one, we added a display title for the sidebar, and then we created this four-sentence-long description, which covers:

• the scope of what the tool is for: postmortems, RFCs, on-call handovers starting from 2023

• when to use it: asking about decisions that have already happened or incidents that have already happened

• what it's not for: it doesn't read the codebase and doesn't see anything filed under drafts

• what it returns: at most twenty matches, newest first, each with a title, date, and a paragraph containing the matching phrase

We also added some metadata next to every parameter:

• keyword is of type string, which is called query, and the tool accepts words to match rather than a question

• YYYY-MM-DD date, optional, called since, if not provided it's set to one year ago from today

So 383 characters of description against 7.

Anthropic recommends at least 3–4 sentences for descriptions (even more for complex tools), and in this example we have four. If we were to look at the 14 descriptions from the filesystem server, they range from 85 to 457 characters.

But the most valuable line of text in this description is this one:

it does not read the codebase and does not see anything filed under `drafts/`

Nobody would ever write it for a colleague, but if you don't include it, the model will try using the tool with a "what's the codebase like" query and return an empty list; then it will conclude that there must be no information about it

The negative space is the valuable part

But now let's talk about what the tool doesn't do. If it has a sibling, the most valuable sentence in its description is the one that points to the other tool. The edgar.tools maintainer phrased it like this:

With sibling tools, the sentence that earns its tokens is "not this — use that."

And their full-text search description ends with an explicit pointer to the event-shaped queries tool. Their financial-statement tools do the same thing with a scope warning — the structured XBRL data doesn't exist until the 10-K or 10-Q is filed, so on earnings day the just-reported quarter is invisible to them, and the description sends that intent elsewhere. Before that sentence existed:

the model confidently answered earnings questions with stale annuals. A description fixed a hallucination class no schema change could.

Their framing is worth stealing — at 27 tools, "you're writing one decision tree distributed across 27 descriptions". And the Docker maintainer from the same thread says the same pattern "cut misrouting roughly in half".

For every tool that has a reasonable neighbour, one sentence describing this neighbour and saying when it should be used. It's not repeating the purpose of this tool (the one you're working on), but a conditional handoff; if they ask about an incident that's still open, point them to the incidents-list tool

The schema is prose too

And the third question — what format each parameter is in. Every description inside inputSchema reaches the model too, so per-parameter text is where the format goes. The spec even has an example:

"location": { "type": "string", "description": "City name or zip code" }

That one phrase tells the model what to put in the string, which is the difference between an argument that works and three retries.

And there are three things that should be said at the parameter level and nowhere else:

• The shape of the values — dates as YYYY-MM-DD, keywords rather than questions, enums where applicable

• The default value applied when the parameter is not provided — a silent one-year window if you don't say anything

• Descriptive parameter names — Anthropic's example is user_id instead of user

And there's another place to put information that the model should be aware of before it decides to call a tool:

the server's retention policy should be stated in the creation tool's description (e.g., "baskets expire after 24 hours of inactivity") so the model can see it when deciding to create state

So just remember that everything the model might need to know at the moment of decision is prose, because there's no other place to put it

Errors are the second draft of your description

Now let's have a look at the error messages as well. The spec splits protocol-level errors from tool-execution errors — the latter are being deliberately surfaced to the model so they carry an actionable feedback for self-correction and trying with modified parameters, and clients are supposed to forward them:

Invalid departure date: must be in the future. Current date is 08/08/2025.

Anthropic also tells tool creators to prompt-engineer the error messages into actionable steps towards specific improvements instead of opaque codes or tracebacks.

So if your server emits an error that the model encounters more than twice, it's a description defect with a stack trace attached. If the model keeps sending a natural-language question to a keyword parameter — you need to say so in the parameter description, not write a stricter validator

Long enough to route, cheap enough to keep

But you need to be mindful of the fact that this is rent; you're paying for the space these descriptions occupy as soon as the definitions are loaded (before the first request, if they load up front). So if you set up five servers (GitHub, Slack, Sentry, Grafana, Splunk) it's gonna be around 55k tokens of definitions before any work is done

If the definitions are deferred instead, it's the model that searches the catalogue for tools and fetches only what it needs — but it changes the cost rather than eliminates it. And btw, the Messages API docs are explicit about it — both variants search over tool names, descriptions, argument names, and argument descriptions. So under deferred loading the description is actually the index entry, and the word a user would actually type has to appear somewhere in that set, otherwise the tool never surfaces to be chosen

So just remember to write sentences that change the routing decisions and delete sentences that repeat the tool name. And if you run this script — the one that pins the 2025-06-18 handshake, which initialises the server and runs tools/list so it can print the definitions sizes, without a model, key or token spent — against the filesystem server, you'll see that it finds 14 tools with 13635 characters of definitions. Against your server, it usually finds something different

python3 scripts/tool-budget.py -- npx -y @modelcontextprotocol/server-filesystem /tmp

The loop

To improve the descriptions, iterate — change wording, read it back, and run the prompt that made it choose the wrong tool last time (the ambiguous one, word for word as whoever reported it phrased it). Keep it, it's a test for this layer. If the model chooses the wrong tool it means you need to improve the description, sentence by sentence, until it stops