Skip to content
IsoKron

Tool names are unique within the server

Tool names SHOULD be unique within an MCP server; with a duplicate, a call can reach either tool, clients keep one and drop the other, and the Claude API refuses a request that carries two tools of the same name.

Check spec-name-unique · MCP specification 2026-07-28 · default severity: attention · rubric 2.1.0

Error message you’ll see

Error
tools: Tool names must be unique.

Claude API (400), when two connected tools end up with the same name. Where this was reported

Error
Tool […] is already registered

TypeScript SDK 2.4.0, registerTool with a name already in use. Where this message comes from

Error
Tool already exists: […]

Python SDK (mcp 2.3.0; a logged warning, the second registration is ignored). Where this message comes from

What fails

With two tools of the same name, a call can reach either one. Clients keep one and drop the other.

The rule

Tool names SHOULD be unique within a server.

Source: MCP specification 2026-07-28: Tools

How to fix it

Rename one of the tools, or remove the duplicate.

  1. Find the duplicated name in the list (generated tools from an OpenAPI spec are a common cause).
  2. Rename one tool so each name says what sets it apart, or remove the duplicate.
  3. Check the whole paginated list: duplicates can sit on different pages.

TypeScript SDK

TypeScript
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';

const server = new McpServer({ name: 'issues', version: '1.0.0' });

server.registerTool(
  'get_issue',
  {
    title: 'Get issue',
    description: 'Return one issue by ID. Use when the user names an issue.',
    inputSchema: z.strictObject({
      issue_id: z.string().describe('Issue ID, for example ISS-42'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ issue_id }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);

Python SDK

Python
from typing import Annotated

from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

server = MCPServer("issues")

@server.tool(
    title="Get issue",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def get_issue(
    issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
) -> str:
    """Return one issue by ID. Use when the user names an issue."""
    return "Done"

Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.

Questions

Is a duplicate name an error or a warning?

The specification says SHOULD, so it is not a protocol error. In practice it fails: the TypeScript SDK throws "Tool ... is already registered", the Python SDK ignores the second tool, and the Claude API rejects requests with duplicate names. OpenAI makes uniqueness a requirement.

Do names have to be unique across servers?

No, only within one server. Clients prefix the server name to keep tools from different servers apart.

How this check is graded

It counts toward: MCP specification 2026-07-28. See the rubric.

Last verified against MCP specification 2026-07-28: Tools on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.

Check your tool list: paste your tools/list, nothing is sent anywhere