Skip to content
IsoKron

MCP tool name length: 1 to 128 characters

MCP tool names should be between 1 and 128 characters (inclusive); the SDKs warn above 128, and the Claude API and Anthropic directory accept at most 64.

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

Error message you’ll see

Error
Tool name exceeds maximum length of 128 characters (current: […])

TypeScript SDK 2.4.0 and Python SDK 2.3.0 warning when the tool is registered. Where this message comes from

Error
Invalid 'tools[3].function.name': string too long. Expected a string with maximum length 64, but got a string with length 67 instead.

OpenAI API, when a client forwards MCP tools as functions. Where this was reported

What fails

Names outside this range may be refused or cut by clients.

The rule

Tool names SHOULD be between 1 and 128 characters in length (inclusive).

Source: MCP specification 2026-07-28: Tools

How to fix it

Shorten the name. The Anthropic directory also requires 64 characters or fewer.

  1. Find names longer than 64 characters (the stricter limit that matters in practice).
  2. Shorten them to a verb and an object, and move detail into the title and description.
  3. Remember that clients prefix the server name (for example mcp__issues__): leave room for it.

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_open_issues',
  {
    title: 'List open issues',
    description: 'List open issues in a project, newest first. Use when the user asks what is open or pending.',
    inputSchema: z.strictObject({
      project_id: z.string().describe('Project ID, for example PRJ-7'),
      limit: z.number().int().min(1).max(100).default(20).describe('Maximum issues to return'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ project_id, 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 open issues",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def list_open_issues(
    project_id: Annotated[str, Field(description="Project ID, for example PRJ-7")],
    limit: Annotated[int, Field(description="Maximum issues to return", ge=1, le=100)] = 20,
) -> str:
    """List open issues in a project, newest first. Use when the user asks what is open or pending."""
    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 the limit 64 or 128 characters?

Both, for different readers. The MCP specification says names SHOULD be 1 to 128 characters. The Anthropic connector checklist and the Claude API require 64 or fewer, and the OpenAI function API also stops at 64. Keep names at 64 or below to work everywhere.

Why does my 60-character name still fail?

Clients prefix the server name to every tool name (Claude Code uses mcp__<server>__<tool>), so the combined name can pass 64 characters. Shorten the tool name or the server name.

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