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

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:

| Example Tool Name | Length |
|-------------------|--------|
| mcp__bcp-trello__TRELLO_ADD_BOARDS_CALENDAR_KEY_GENERATE_BY_ID_BOARD | 68 chars |
| mcp__bcp-trello__TRELLO_GET_ORGANIZATIONS_MEMBERSHIPS_BY_ID_ORG_BY_ID_MEMBERSHIP | 80 chars |
| mcp__bcp-google-calendar__GOOGLECALENDAR_EVENTS_LIST_ALL_CALENDARS | 65 chars |

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:

``json
{
"env": {
"ENABLE_TOOL_SEARCH": "false"
}
}
``
Downside: All MCP tools load into context, increasing token usage significantly.

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

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

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

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

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

Related Issues

• #19882 - Tool search fails when MCP tool names exceed 64 chars
• #18015 - MCPSearch tool_reference tool_name exceeds 64-character API limit
• #21136 - API Error 400: MCP tool names exceeding 64 character 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