[FEATURE] Align tool_reference.tool_name character limit with tool.name (128 characters)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When using MCP tools through plugins in Claude Code, I encounter a 64-character limit on tool_reference.tool_name that prevents tool invocation, even though tool.name (for tool definitions) was reportedly increased to 128 characters in June 2025.

The naming convention for plugin-based MCP tools follows the pattern:
mcp__plugin_{plugin-name}_{server-name}__{tool-name}

This structure easily exceeds 64 characters, making it impossible to use legitimately-named plugins and MCP servers together. This affects my workflow when integrating third-party MCP servers through the plugin system.

Proposed Solution

Option 1 (Preferred): Increase the tool_reference.tool_name character limit to 128 characters to match the tool.name limit that was already increased.

Option 2: If the 64-character limit must remain for technical reasons, provide clear documentation in the official API docs about:

• The distinction between tool.name (128 chars) and tool_reference.tool_name (64 chars) limits
• Best practices for naming plugins and MCP servers to stay within limits
• Validation errors that occur before tool invocation

Alternative Solutions

Current workaround: Manually shorten plugin or MCP server names in configuration files.

Limitations of workaround:

• Breaks compatibility with officially-named plugins/servers
• Requires manual intervention for every MCP server integration
• Creates inconsistency between plugin names and their actual identifiers
• Difficult to maintain when using multiple plugins

Other approaches considered:

• Using shorter tool names within MCP servers (not always controllable by end users)
• Avoiding the plugin system entirely (loses plugin functionality)

Priority

High - Significant impact on productivity

Feature Category

API and model interactions

Use Case Example

Scenario: Integrating a documentation lookup MCP server through a plugin

Steps:

1. Install Claude Code with a plugin named sontixyou-plugin
2. Configure an MCP server named context7 within the plugin
3. The MCP server provides a tool: resolve-library-id
4. Attempt to use the tool via MCPSearch

Expected behavior:
The tool is invoked successfully.

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

Analysis:

• Generated tool reference name: mcp__plugin_sontixyou-plugin_context7__resolve-library-id
• Length: 66 characters (2 over limit)
• Tool definition succeeded, but tool invocation failed

Additional Context

Environment:

• Claude Code version: 2.0.76
• Date: 2026-01-06
• Platform: macOS (Darwin 24.6.0)

Error message:
tool_reference.tool_name: String should have at most 64 characters

Key observation:
The error path tool_reference.tool_name differs from tools.X.custom.name seen in rel

1. tool.name (tool definition): 128 characters
2. tool_reference.tool_name (tool invocation): 64 characters

Related issues:

• #2536 - Similar issue during MCP server addition
• #2485 - Tool name length exceeds 64 characters
• #2412 - MCP tool validation enhancement (marked as resolved with 128-char increase)

Documentation gap:
The 64-character limit for tool_reference.tool_name is not documented in:

• https://platform.claude.com/docs/en/api/messages
• https://platform.claude.com/docs/en/docs/build-with-claude/tool-use

This makes it difficult for plugin and MCP developers to design compliant tool names.

Investigation:
I searched the official API documentation and found no mention of character limits for tool names. The limit only appears in API error messages, suggesting it's an undocumented validation rule.