[BUG] ToolSearch returns tool_reference with names exceeding 64-character API limit, breaking entire session #22455

Bug Description

When ToolSearch returns MCP tools with names exceeding 64 characters, the API returns a 400 error that breaks the entire session. The user cannot send any further messages until the MCP server is disabled or removed.

Error Message

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.X.content.0.tool_result.content.0.tool_reference.tool_name: String should have at most 64 characters"},"request_id":"req_..."}

Root Cause Analysis

MCP tool names follow the format: mcp__[server_name]__[tool_name]

For Composio-based MCP servers (and others with verbose tool names), this combined string easily exceeds 64 characters:

Key finding: Even shortening the server name to a single character (t) is insufficient for tools with very long names:

• mcp__t__TRELLO_GET_ORGANIZATIONS_MEMBERSHIPS_BY_ID_ORG_BY_ID_MEMBERSHIP = 70 characters (still exceeds limit)

Steps to Reproduce

1. Configure an MCP server with tools that have long names (e.g., Composio Trello, Google Calendar)
2. Start a Claude Code session
3. Send any prompt that triggers ToolSearch to discover MCP tools
4. Observe API Error 400

Critical Issue: Session Becomes Unresponsive

The most severe aspect of this bug is that once the error occurs, the entire session becomes unusable. Every subsequent message triggers the same error because:

1. ToolSearch runs automatically on prompts
2. The tool_reference with the long name is included in the API request
3. API rejects the request before any processing

The user must either:

• Disable the offending MCP server
• Set ENABLE_TOOL_SEARCH=false
• Start a completely new session

Inconsistent Behavior Across Projects

Interestingly, the same MCP server may work in one project directory but fail in another, likely due to:

• Different ToolSearch queries returning different tool subsets
• Some queries return only short-named tools (works)
• Other queries return long-named tools (fails)

Environment

• Claude Code version: 2.1.29
• Platform: Linux (WSL2)
• MCP servers tested: Composio Trello, Composio Google Calendar, Composio YouTube

Current Workarounds

1. Disable ToolSearch per-project: Add to .claude/settings.json:

   {
     "env": {
       "ENABLE_TOOL_SEARCH": "false"
     }
   }

   Downside: All MCP tools load into context, increasing token usage significantly.

2. Disable long-named MCP servers: Not ideal if you need those integrations.

Proposed Solutions

1. Validate/truncate tool names at registration: When MCP servers are loaded, validate that mcp__[server]__[tool] ≤ 64 chars. Warn or auto-truncate.

2. Hash long tool names: For tools exceeding the limit, use a shortened hash-based identifier internally while maintaining the full name for display.

3. Graceful degradation in ToolSearch: If a tool name exceeds the limit, skip that specific tool rather than failing the entire request.

4. Increase API limit: Coordinate with API team to increase the 64-character limit for tool names.

5. Allow custom prefixes: Let users configure shorter prefixes or disable the mcp__ prefix entirely.

Related Issues

• [BUG] Tool search fails when MCP tool names exceed 64 chars #19882 - Tool search fails when MCP tool names exceed 64 chars
• [Bug] MCPSearch tool_reference tool_name exceeds 64-character API limit #18015 - MCPSearch tool_reference tool_name exceeds 64-character API limit
• [BUG] API Error 400: MCP tool names exceeding 64 character limit #21136 - API Error 400: MCP tool names exceeding 64 character limit
• core-mcp-server: billing_cost_management prefix causes tool names to exceed 64-char API limit awslabs/mcp#2214 - billing_cost_management prefix causes tool names to exceed 64-char API limit

Impact

This bug effectively prevents users from using any MCP server with verbose tool names (common in enterprise integrations like Composio). It's particularly frustrating because:

1. The error is not immediately obvious (no clear indication which tool caused it)
2. The session becomes completely unresponsive
3. Workarounds require disabling useful features (ToolSearch) or integrations