{"record":{"id":"37e8cac0ecfe8b2c","repo":"shareAI-lab/learn-claude-code","slug":"mcp-tool-name-is-longer-than-64-characters-prefi","errorCode":null,"errorMessage":"MCP tool name is longer than 64 characters: {prefixed}","messagePattern":"MCP tool name is longer than 64 characters: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"s14_mcp_plugin/code.py","lineNumber":331,"sourceCode":"def assemble_tool_pool() -> tuple[list[dict], dict[str, callable]]:\n    \"\"\"Combine built-in tools with every connected server tool.\"\"\"\n    global mcp_tool_policies\n    tools = list(BUILTIN_TOOLS)\n    handlers = dict(BUILTIN_HANDLERS)\n    policies: dict[str, str] = {}\n    origins = {\n        tool[\"name\"]: f\"built-in tool {tool['name']!r}\"\n        for tool in tools\n    }\n\n    for server_name, server in mcp_clients.items():\n        safe_server = normalize_mcp_name(server_name)\n        for tool_def in server.tools:\n            raw_name = tool_def[\"name\"]\n            safe_tool = normalize_mcp_name(raw_name)\n            prefixed = f\"mcp__{safe_server}__{safe_tool}\"\n            if len(prefixed) > 64:\n                raise ValueError(f\"MCP tool name is longer than 64 characters: {prefixed}\")\n            origin = f\"MCP tool {server_name!r}/{raw_name!r}\"\n            if prefixed in origins:\n                raise ValueError(\n                    \"MCP tool name collision after normalization: \"\n                    f\"{prefixed!r} maps both {origins[prefixed]} and {origin}\"\n                )\n            schema = tool_def.get(\"inputSchema\", {})\n            if not isinstance(schema, dict) or schema.get(\"type\", \"object\") != \"object\":\n                raise ValueError(f\"Invalid input schema for {origin}\")\n            origins[prefixed] = origin\n            tools.append({\n                \"name\": prefixed,\n                \"description\": tool_def.get(\"description\", \"\"),\n                \"input_schema\": schema,\n            })\n            handlers[prefixed] = (\n                lambda *, client=server, tool=raw_name, **kwargs:\n                client.call_tool(tool, kwargs)","sourceCodeStart":313,"sourceCodeEnd":349,"githubUrl":"https://github.com/shareAI-lab/learn-claude-code/blob/985456f4adea6f4df8fbad4112245dbd97444eae/s14_mcp_plugin/code.py#L313-L349","documentation":"When building the unified tool catalog, each MCP tool becomes 'mcp__<server>__<tool>' (both parts normalized). The model's tool-name limit is 64 characters, so a prefixed name longer than that raises ValueError at catalog-build time — better than shipping a tool the model can never call.","triggerScenarios":"A server named 'internal-documentation-platform' with a tool named 'search_across_all_versions' produces a >64-char prefixed name; long hyphenated server names from config; verbose auto-generated tool names.","commonSituations":"Real-world MCP server names (often domain-like) combined with descriptive tool verbs; mirrors of external APIs with long method names.","solutions":["Shorten the server name in its MCPClient('name') constructor (biggest lever, it appears once per tool).","Rename the offending tool(s) to concise verbs.","Budget: total = 6 + len(server) + 2 + len(tool); keep server+tool under ~56 chars."],"exampleFix":"// before\nserver = MCPClient('internal-documentation-platform')\n// tool 'search_across_all_versions' -> prefixed 60+? over 64 -> ValueError\n\n// after\nserver = MCPClient('docops')  // 'mcp__docops__search_across_all_versions' fits","handlingStrategy":"validation","validationCode":"def prefixed_name_len(server: str, tool: str) -> int:\n    return len(f'mcp__{server}__{tool}')\n\ndef fits_model_limit(server: str, tool: str) -> bool:\n    return prefixed_name_len(server, tool) <= 64","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep MCP server names short (<= 20 chars) — they tax every tool name.","Name tools with concise verbs; budget 6 + server + 2 + tool <= 64.","Add a CI check that builds the catalog against the real config to catch long names early."],"tags":["mcp","name-length","validation","tool-registration"],"backgroundTag":null,"analyzedSha":"985456f4adea6f4df8fbad4112245dbd97444eae","analyzedAt":"2026-08-14T22:02:26.028Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}