Two MCP Servers Share a Tool Name and Your Agent Calls the Wrong One
You wired several MCP servers into one agent, and two of them expose a tool called search. The MCP spec gives a tool name no namespace across servers, so your client has to decide which one wins and the model has to guess which one it meant.
You wired eight MCP servers into one agent last sprint, because that is the whole promise of the protocol: pick the integrations you want and the agent gets their tools for free. It worked. Then a ticket came in that an agent run searched the wrong system. The user asked it to search the codebase, and it searched the web instead, confidently, and summarized a blog post as if it were your repo. You check the trace. The model called search. Which search? You have three servers that expose a tool named search, and nothing in the trace tells you which one answered, because as far as the model and the transcript are concerned there is only one tool with that name.
Here is the part the protocol does not advertise. The Model Context Protocol defines a tool's name as a unique identifier, but unique within a single server. The spec says nothing about what happens when two servers you connect both export search, create_issue, or get_user. There is no namespace, no required disambiguation scheme, and no rule for which one wins. That decision falls entirely to your client, and most clients make it silently. So the agent does not see "the GitHub server's search" and "the web server's search." It sees one search, and the mapping from that word to an actual server is made somewhere you are not looking.
One name is not an identity
The quiet assumption inside most agent stacks is that a tool call is unambiguous: the model emits a name, you look it up, you run it. That holds when every tool name is globally unique. It stops holding the moment you let a user compose their own set of servers, which is exactly what MCP is for. Microsoft Research made this concrete when it analyzed nearly 1,500 public MCP servers for its tool-space interference study and found that naming is one of the main ways independently built tools clash: two tools cannot share a name in a single provider API call, and semantically overlapping names like search, web_search, and bing_search confuse the model even when they do not collide outright.
The reason this is dangerous rather than merely annoying is that a tool name is doing two jobs at once, and they pull in opposite directions. To the dispatcher, the name is a routing key: it has to resolve to exactly one piece of code. To the model, the name is a lexical cue: it reads create_issue and infers what the tool does and when to pick it. A NeurIPS 2026 paper, Names Lie, Registries Bind, pulled those two roles apart deliberately and measured what happens when the label a model reads conflicts with the identifier a registry binds to. On small tool-calling models the gap was not subtle: exact-call accuracy dropped by 27 points on one model and far more on another once the names stopped agreeing with the bindings. The name you show the model and the name you route on cannot be the same loose string if you want the call to land where you meant.
This is a cousin of the confused deputy problem, where an agent with real authority is tricked into using it on the wrong target. A collision is a confused deputy by accident: the agent has the authority to search, it uses it, and the target is chosen by whichever server happened to register the name first.
The three ways a collision resolves, all bad
When two servers export the same tool name and your client flattens them into one list, exactly one of three things happens, and you usually do not get to pick which.
The client rejects the whole set. The stricter SDKs raise a duplicate-tool error at startup and refuse to run, which is the honest failure but also the one that turns "add a server" into a debugging session. You find out at least, but the agent is down until someone renames something.
The client silently keeps one. Last-write-wins or first-write-wins, depending on load order, and the loser vanishes. The agent now has a search that points at one server and no way to reach the other, and nobody decided that on purpose. This is the version that produces the wrong-system ticket, because load order is not something your users reason about.
The model picks from ambiguous cues. If the client does expose both, it has to label them somehow, and if the labels are weak the model guesses from the description. Now you are relying on an 8B router to disambiguate two tools that an engineer could not be bothered to name differently. This is the same failure surface I wrote about in retrieving the right tool from hundreds, except here the two candidates are not merely similar, they are identical in the one field the dispatcher trusts.
None of these is safe by default, and all three share a root cause: the name is being asked to be a global identifier when it was only ever promised to be a local one.
Namespace every tool at the client boundary
The fix is the same one every other system with this problem reached: give each tool a name that includes where it came from, and do it at the boundary where you first learn which server a tool belongs to. You already know the server identity at list time, because you are the one who opened the connection. Qualify the name there, before the flat list ever reaches the model or the dispatcher.
import re
# At tools/list time you still know which server each tool came from. Bind that
# in now, because this is the last point where the mapping is unambiguous. After
# this, the model only ever sees the qualified name and the dispatcher only ever
# routes on it, so a bare "search" can never reach anything.
def qualify(server_id: str, tool: dict) -> dict:
safe = re.sub(r"[^a-zA-Z0-9_]", "_", server_id)
return {**tool, "name": f"{safe}__{tool['name']}", "_server": server_id}
def build_catalog(sessions: dict[str, list[dict]]) -> dict[str, dict]:
catalog: dict[str, dict] = {}
for server_id, tools in sessions.items():
for tool in tools:
q = qualify(server_id, tool)
# Two servers can share a bare name but never a qualified one.
catalog[q["name"]] = q
return catalog
The qualified name is what the model sees in its tool list and what it emits when it decides to call. Your dispatcher splits the prefix back off, routes to the right session, and calls the server with the original bare name the server expects. The server never knows it was namespaced. The collision is gone because github__search and web__search are different strings everywhere that matters.
Two details make this hold up. Use a separator that cannot appear in a legitimate tool name, like a double underscore or a dot, so splitting is unambiguous and an attacker cannot smuggle a prefix inside their own name to impersonate another server. And keep the prefix stable across sessions, because it becomes part of what you approved and what you pin, which is the next piece.
Pin the binding, not just the name
Namespacing stops the accidental collision. It does not, on its own, stop the adversarial one. An attacker who controls a server can watch which prefix scheme your client uses and register a tool whose qualified name lands on top of a trusted one, or lean on the fact that the model reads descriptions as instructions. Invariant Labs demonstrated the mechanism as MCP tool shadowing: a malicious server does not even need to be called. Its tool description, sitting in the agent's context alongside everyone else's, carries hidden instructions about how to use a different, trusted tool, and the agent obeys them.
So the qualified name has to be bound to a specific server identity and a specific schema that a human actually approved, not just to whatever currently answers to that string. This is the same instinct as fingerprinting each tool definition at approval time: you pin what was approved and refuse anything that does not match. Here you pin the binding itself, the triple of qualified name, server, and schema hash.
import hashlib, json
def schema_hash(tool: dict) -> str:
blob = json.dumps(tool.get("inputSchema", {}), sort_keys=True, separators=(",", ":"))
return hashlib.sha256(blob.encode()).hexdigest()[:16]
# A binding is the whole identity, not just the name. At approval we write one
# binding per qualified name. At call time the live tool must match all three.
def resolve(qualified_name: str, catalog: dict, approved: dict):
live = catalog.get(qualified_name)
if live is None:
raise LookupError(f"no tool bound to {qualified_name}")
pin = approved.get(qualified_name)
if pin is None:
# A qualified name that appeared after approval. New capability, new
# decision. Default deny, do not auto-trust it because the name looks fine.
raise PermissionError(f"unapproved binding {qualified_name}")
if live["_server"] != pin["server"] or schema_hash(live) != pin["schema"]:
# Same name, different server or schema than the human approved. This is
# exactly what shadowing looks like from the inside. Stop.
raise PermissionError(f"binding drift on {qualified_name}")
return live
The unapproved-binding branch is the one people skip, and it is the one that catches a new tool quietly appearing to shadow an old one. A qualified name you have never approved is not a convenience to resolve, it is a decision to route to a human. Treat it the way you would verify an agent card before trusting a peer: identity first, then capability, and never the other way around.
What the model sees still has to be unambiguous
Pinning fixes the dispatch side. It does not fix the model side, because the model still has to choose the right tool from your catalog in the first place, and github__search versus web__search is only legible if the model can tell from context which system the user meant. Two tools that are genuinely different jobs should read as genuinely different in the one field the model reasons over, the description, not just in a prefix it may skim past.
# The prefix disambiguates for YOU. The description disambiguates for the MODEL.
# If both tools say "Search for information", the router is guessing. Make the
# scope explicit in the first sentence, where the model actually reads it.
def clarify_description(tool: dict) -> dict:
server = tool["_server"]
desc = tool.get("description", "")
scoped = f"[{server}] {desc}".strip()
# Flag the near-collisions the prefix alone will not save you from.
tool["description"] = scoped
return tool
This is cheap and it closes the semantic-collision gap the Microsoft study flagged, where search, web_search, and bing_search coexist without ever being true duplicates. A stable prefix keeps the dispatcher honest. A scoped first sentence keeps the model honest. You need both, because a call that routes perfectly to the tool the model should not have chosen is still the wrong answer, just a well-plumbed one.
The parts that bite
Namespacing changes the names the model sees, so it changes your prompt cache and sometimes your evals. If you add the prefix after shipping, every tool name in your system prompt shifts, which invalidates cached prefixes and can move model behavior on borderline tool choices. Roll it out behind the same discipline you would use for any change to the tool list, and re-run your tool-selection evals on the new names before you trust the old numbers.
A prefix is not an authentication. Qualifying github__search proves nothing about whether that server is really GitHub's. The prefix stops accidental collisions and gives you a stable key to pin, but the trust in the binding comes from the approval and the schema hash, not from the string. If the server identity itself can be spoofed, you are back to confirming who the server is before you confirm what its tools do.
Descriptions are still untrusted input. Scoping the first sentence helps the model route, but a hostile server controls the rest of that description, and shadowing lives precisely there. Namespacing and pinning do not replace the prompt-injection defenses you run on tool content; they sit in front of them. A pinned, correctly routed tool can still return poisoned data, and a trusted description can still carry an instruction aimed at a different tool.
Clients differ, so do not assume the one you ship on namespaces at all. Some prefix with the server name, some prefix with a short id, some do nothing and let the first server win. If you are building the agent, own the catalog construction yourself rather than inheriting whatever flattening your framework happened to pick, because the default is the thing that produced the wrong-system ticket.
The takeaway
MCP made it trivial to compose tools from servers that never knew about each other, and it left one assumption unstated: that a tool name is a global identity. It is not. It is a local label, unique inside one server and promised nothing beyond that, and the moment you connect two servers you are responsible for the binding the protocol declined to define. The accidental version of the gap misroutes a search. The adversarial version lets a server you never called change what a server you trust does.
The fix is not exotic and you can ship it this week. Qualify every tool with its server at the client boundary so two servers can never collapse to one string, pin each qualified name to the server and schema a human approved, default to deny on any binding you have not seen, and make the description say which system the tool actually touches so the model's choice is as unambiguous as the dispatcher's. If you have several MCP servers wired into one agent and you cannot say which search a given run called, book a consultation call and we can map your tool bindings before load order makes the decision for you.
Questions this essay answers
01What is an MCP tool name collision?
A collision is when two connected MCP servers expose a tool with the same name, like search or create_issue. The MCP spec defines a tool name as a unique identifier within one server, but it says nothing about uniqueness across servers, so a client wiring several servers together inherits two tools that answer to one string. The client then has to decide which one the agent reaches, and the model has to decide which one it meant. Both decisions can go wrong quietly, with no error and no log line that says a choice was even made.
02How is tool shadowing different from an accidental collision?
An accidental collision is two honest servers that happen to pick the same name. Shadowing is an attacker doing it on purpose: a malicious server registers a tool with the same name as a trusted one, hoping your client resolves the name to the attacker's version or that the model reads the attacker's description as instructions. The mechanism is identical, which is the point. If your client cannot tell two same-named tools apart safely, it cannot tell an accident from an attack, so the fix for one is the fix for the other.
03Does the MCP spec provide tool namespacing?
No. As of the 2025-06-18 specification, a tool's name field is described as a unique identifier, but the spec does not define any namespace across servers and gives clients no required scheme for disambiguating tools from different servers. Clients have each invented their own workaround, most commonly prefixing the tool name with the server name. Because the scheme is client-specific and not part of the protocol, you cannot assume any given client namespaces tools at all, which is why you verify it yourself.
04How do I stop my agent from calling the wrong tool on a collision?
Namespace every tool at the client boundary by giving it a server-qualified name the model sees and the dispatcher routes on, so two servers can never map to one string. Pin each qualified name to the specific server and schema a human approved, and default to deny when a name resolves to more than one binding or to a binding you have not seen. That turns a silent misroute into a loud, reviewable event instead of a tool call that lands somewhere no one chose.
