# 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. Last verified against MCP specification 2026-07-28: Tools on 2026-11-18.

## Error message you’ll see

```text
tools: Tool names must be unique.
```

Claude API (400), when two connected tools end up with the same name. Where this was reported: https://github.com/anthropics/claude-code/issues/12994

```text
Tool […] is already registered
```

TypeScript SDK 2.4.0, registerTool with a name already in use. Where this message comes from: https://github.com/modelcontextprotocol/typescript-sdk/blob/951fe5603a7ec0b2dcb6a0b95d92cd86f93ad9e5/packages/server/src/server/mcp.ts#L1103

```text
Tool already exists: […]
```

Python SDK (mcp 2.3.0; a logged warning, the second registration is ignored). Where this message comes from: https://github.com/modelcontextprotocol/python-sdk/blob/2118f14f8a19bc158d8a1cf90af58d85d187f849/src/mcp/server/mcpserver/tools/tool_manager.py#L64

## 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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#tool-names)

## 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

```ts
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"
```

## 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.

## Related checks

- [Tool names are unique within the server (ChatGPT)](https://isokron.ai/mcp-check/checks/openai-name-unique)
- [The paste holds the whole tool list](https://isokron.ai/mcp-check/checks/spec-pagination-partial)
- [Larger catalogs use a naming prefix](https://isokron.ai/mcp-check/checks/design-namespace)
- [MCP tool names](https://isokron.ai/mcp-check/checks/names)

Counts toward: MCP specification 2026-07-28.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
