Two servers, one tool name

// scoped to a single server

The rule is in the spec's own tool-name section, and both halves of it matter:

Tool names SHOULD be unique within a server.

Within a server — and SHOULD, not MUST. There is no registry, no reservation, nothing that stops the next server you install from shipping the same string. The spec says so directly, and picks the example everyone eventually hits:

Tool name uniqueness is scoped to a single server. Clients or proxies that aggregate tools from multiple servers MAY encounter naming collisions (for example, two servers each exposing a search tool) and SHOULD implement a disambiguation strategy such as prefixing tool names with a server identifier.

The failure is that it works

This is not a crash, and that is what makes it expensive. From the model's side the two tools are the same object: the same name, the same shape, nothing to prefer one over the other.

# what the model is handed { name: "search", description: "Search the knowledge base", inputSchema: {...} } { name: "search", description: "Search the knowledge base", inputSchema: {...} } no field distinguishes these two

So it picks one. The call returns isError: false, the content is well-formed, the agent carries on. What you get is an answer sourced from the wrong system — which is much harder to notice than an exception, and much harder to notice late.

A tool's title does not rescue you either. The spec calls it an "Optional human-readable name of the tool for display purposes". The call goes by name.

Prefix them — but not with the server's own name

The mitigation is the obvious one: put a label in front, so the two become two.

docs.search tickets.search

The trap is in the very next sentence of the same spec note, and it disqualifies the prefix most people reach for first:

The server name (from serverInfo) is not guaranteed to be unique across servers and SHOULD NOT be relied upon for disambiguation.

A server names itself. Two projects can pick search-server with no coordination and neither is wrong. So the identifier has to be one you assign, at the point you install the server — a key in your MCP config, not a string the server reports about itself.

# the prefix comes from the key on the left, which you control { "docs": { "command": "npx", "args": ["-y", "@acme/docs-mcp"] }, "tickets": { "command": "npx", "args": ["-y", "@acme/tickets-mcp"] } }

What a name is allowed to be

The character rules are permissive enough that a prefix fits comfortably, and strict enough to be worth checking before you invent a separator.

length 1 to 128 characters case case-sensitive allowed A-Z a-z 0-9 _ - . avoid spaces, commas, other punctuation

Dot-separated prefixes (docs.search) and underscore ones (docs_search) are both inside the allowed set. Pick one and keep it, because the model reads the prefix as part of the name and an inconsistent scheme costs you the clarity you added it for.

If you write servers, assume aggregation

Your server is not the only one installed, and you do not get to see the others. Two habits cost nothing and remove most of the risk:

search collides with everything get list query same search_tickets survives being installed next to anything

And keep the set of names stable. A renamed tool is, to the client's config, a different tool — whatever prefixing it had is now pointing at nothing.

Related: why your agent ignored the tool you gave it covers how to write a single tool so the model reaches for it — the problem this page describes is the one no description on your own server can fix, because you do not own the other one. What an MCP server actually is is the ground underneath, and tools versus resources is the other thing worth settling before you build one.

Source: Model Context Protocol specification (draft), Tools — Tool Names. Verified 2026-09-12.

One concept a week. Free.

The deeper, copy-paste version of each ToolCall short — in your inbox.

// total: 0.00 · spam: void · unsubscribe: one click