Home · Guides

Tool names are unique inside your server and nowhere else

The MCP specification, revision 2026-07-28, states the rules as SHOULDs rather than MUSTs, which means clients vary and the safe move is to satisfy all of them:

Between 1 and 128 characters inclusive.
Case-sensitive. getUser and getuser are different tools.
Allowed characters: A-Z, a-z, 0-9, underscore, hyphen and dot. No spaces, no commas, nothing else.
Unique within a server.

The specification's own valid examples are getUser, DATA_EXPORT_v2 and admin.tools.list, so there is no house style being imposed. Pick one and hold it.

The part that catches people

Uniqueness is scoped to a single server. The specification then says what follows: clients or proxies that aggregate tools from several servers may hit collisions, for example two servers each exposing a search tool, and SHOULD prefix with a server identifier to disambiguate. It adds a warning that is easy to miss: the server name from serverInfo is not guaranteed to be unique across servers and SHOULD NOT be relied upon for disambiguation.

So the thing you would naturally reach for as a prefix is explicitly ruled out as a unique key. Whatever prefix a host uses is the host's business, which means your tool may be presented to a model as myserver__search, mcp_myserver_search or something else entirely, and the name the model actually sees is longer than the one you wrote.

A measured example of the collision

This project publishes a catalogue of MCP servers. Two tools, license_activate and license_status, come from a package vendored into every one of them, so every hosted endpoint ships the identical pair of names. Probed unauthenticated on 2026-09-09:

/mcp/invoice               13 tools
/mcp/spreadsheet           13 tools
/mcp/zip                   12 tools
/mcp/catalogue             12 tools
/mcp/timezone              11 tools
/mcp/barcode               10 tools
/mcp/statement-of-account   8 tools

Every one of those lists contains license_activate. Connect two of them to the same client and the host has to disambiguate or one wins. That is not a bug in any of the servers, it is the scope rule doing exactly what it says, and it is the normal outcome of shipping a shared package across a fleet.

Why the name and the description are worth more than the code

A model picks a tool by reading its name and description, so those strings are the interface even though the code is the product. Directories score them for the same reason. Glama's published methodology, section 1.6, read 2026-09-09, scores every tool on six dimensions, each 1 to 5: Purpose Clarity, Usage Guidelines, Behavioral Transparency, Parameter Semantics, Conciseness, and Contextual Completeness. Its own summary of what it finds across public servers is that 97 percent of tools carry at least one defect, 56 percent do not make clear what the tool does, and 89 percent omit usage constraints.

The scoring weight is the part that changes behaviour. On the score page for a listed server the formula is 0.6 times the mean of the tool scores plus 0.4 times the minimum, then 70 percent of the overall grade against 30 percent for coherence. Read that again: 40 percent of the definition score is your single worst-described tool. Measured across 20 of this project's connectors on 2026-09-08, the minimum-scoring tool was license_activate on 20 of 20, mean 2.26 against 4.12 for license_status, which lives three lines away in the same file and was written in the same style. One string held down a fleet.

A naming checklist that survives a proxy

Use one convention across the server. Mixed verbs, gerunds and nouns cost coherence points and make a list harder to read.
Put the object before the verb, so related tools sort together: invoice_create and invoice_send rather than create_invoice and send_invoice.
Keep it short enough that a host prefix does not push it past a limit you do not control.
Avoid bare generics. search, list, get and run are the names most likely to collide in an aggregated client.
Never rename a published tool. Every caller, proxy and saved workflow keys on the string.

Sources: the tools section of the MCP specification, revision 2026-07-28, fetched 2026-09-09, for the naming rules and the disambiguation guidance; glama.ai/mcp/methodology section 1.6, read the same day, for the six scoring dimensions and its published survey figures; the tool counts above measured against this project's live endpoints on 2026-09-09; the per-connector scores recorded in data/glama_r2.json in this repository.

Questions

Are the naming rules MUSTs?

No, the specification uses SHOULD throughout that section. In practice a client that rejects a name is worse for you than a name you did not want, so treating the SHOULDs as hard rules costs nothing and removes a class of failure you cannot debug from your side.

snake_case or camelCase?

The specification's examples include both and neither is preferred. Consistency inside one server is what gets scored and what a reader notices. Switching style halfway through a tool list is the actual defect.

How long should a description be?

Long enough to say what the tool does, when to call it, when not to, and what it changes. Claude Code truncates tool descriptions and server instructions at 2KB each, in its own documentation read 2026-09-09, so that is the practical ceiling. The common failure is the opposite: a single clause that repeats the tool name in different words.

Can I have a tool with no parameters?

Yes. The inputSchema still has to be a valid JSON Schema object, and the recommended form is {"type": "object", "additionalProperties": false}. Passing null is invalid.

What if two of my own servers need the same tool name?

That is legal, because uniqueness is per server, and it is what happens with any shared package. Just expect a client running both to prefix them, and do not build anything that depends on the model seeing your exact string.

All MCP servers and prices · All guides · Buy the bundle $39