Skip to content
IsoKron

Tool names are unique within the server (ChatGPT)

OpenAI’s plugin guidelines state that tool names must be unique within your MCP server, so a duplicate name blocks a ChatGPT app submission even though the MCP specification only says SHOULD.

Check openai-name-unique · OpenAI plugin directory · default severity: blocking · 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

What fails

OpenAI makes uniqueness a requirement (the MCP specification says SHOULD).

The rule

Tool names must be unique within your MCP server.

Source: OpenAI plugin guidelines, section 6.1

How to fix it

Rename or remove the duplicate tools.

  1. List every tool name and find the repeats.
  2. Rename one of each pair to describe what it does differently, or remove it.
  3. Re-submit only after the full list (all pages) has no repeats.

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(
  'list_projects',
  {
    title: 'List projects',
    description: 'List the projects the user can see. Use when the user asks which projects exist.',
    inputSchema: z.strictObject({
      limit: z.number().int().min(1).max(100).default(50).describe('Maximum projects to return'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ limit }) => ({ 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="List projects",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def list_projects(
    limit: Annotated[int, Field(description="Maximum projects to return", ge=1, le=100)] = 50,
) -> str:
    """List the projects the user can see. Use when the user asks which projects exist."""
    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

How can a server list the same name twice?

Usually by generating tools: two OpenAPI operations that map to one name, a plugin system that registers a tool twice, or two pages of a paginated list that overlap.

Does case matter?

Tool names are case-sensitive in the specification, but Get_Issue and get_issue next to each other confuse models and reviewers. Use one spelling.

How this check is graded

It counts toward: OpenAI plugin directory. See the rubric.

Last verified against OpenAI plugin guidelines, section 6.1 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