Validation Error: Insufficient Context for Tool Name Length Constraint

Status Fixed / completed

Maintainer reply ✓ Yes — ashwin-ant

Activity 7 comments · opened Jun 21, 2025 · closed Jun 25, 2025

💡 Likely answer: A maintainer (ashwin-ant, collaborator) responded on this thread — see the highlighted reply below.

Enhancement: Improve MCP tool validation error messages with server and tool context

Issue Type

[x] Enhancement Request
[ ] Bug Report

Summary

Currently, when MCP tools have names exceeding 64 characters, Claude Code shows generic validation errors without context about which server or tool is problematic. This makes debugging difficult for users with many MCP servers.

Current Behavior

/dart:Create doc (MCP)
⎿ API Error: 400 
  {"type":"error","error":{"type":"invalid_request_error","message":"tools.187.custom.name: String 
  should have at most 64 characters"}}

Problems:

No indication of which MCP server provides the tool
No display of the actual problematic tool name
Requires manual counting to find tool #187
No guidance on how to fix the issue

Proposed Enhancement

Enhanced Error Message (Example)

❌ MCP Tool Validation Failed

Server: enterprise-database-management
Tool #187: mcp__enterprise-database-management__synchronize-all-customer-data-across-multiple-systems
Length: 90/64 characters (26 over limit)

💡 Suggested name: mcp__ent-db__sync-customer-data

🔧 How to fix:
• Update tool name in 'enterprise-database-management' MCP server configuration
• Use abbreviations: 'db' instead of 'database-management'  
• Remove redundant prefixes where possible

📚 Documentation: https://docs.anthropic.com/claude-code/mcp#tool-naming

Note: The above shows a hypothetical enhanced error message. The actual error only shows "tools.187.custom.name: String should have at most 64 characters" without any context about which server or tool is problematic.

Implementation Benefits

Immediate Problem Identification: Users know exactly which server/tool is broken
Actionable Guidance: Clear suggestions for fixing the issue
Time Savings: No manual tool counting or configuration hunting
Better UX: Professional error handling with helpful context

Technical Approach

1. Enhanced Validation During Tool Loading

interface ToolValidationError {
  mcpServer: string;
  toolName: string; 
  toolIndex: number;
  actualLength: number;
  maxLength: number;
  suggestedName: string;
}

2. Smart Name Suggestions

Remove redundant prefixes (mcp__)
Apply common abbreviations (management → mgmt)
Truncate intelligently at word boundaries
Preserve tool functionality clarity

3. Improved CLI Error Display

Colored output for visibility
Step-by-step fix instructions
Links to relevant documentation
Context about which server to modify

Use Cases

Enterprise Users: Managing 50+ MCP tools across multiple servers
Plugin Developers: Testing new MCP servers with descriptive tool names
Support Teams: Helping users debug MCP configuration issues
New Users: Learning MCP tool naming best practices

Environment Info

Platform: darwin
Terminal: vscode
Claude Code Version: 1.0.31

Related Error Logs

[
  {
    "error": "Error: Command failed: security find-generic-password -a $USER -w -s \"Claude Code\"\nsecurity: SecKeychainSearchCopyNext: The specified item could not be found in the keychain.\n\n    at genericNodeError (node:internal/errors:983:15)\n    at wrappedFn (node:internal/errors:537:14)\n    at checkExecSyncError (node:child_process:892:11)\n    at execSync (node:child_process:964:15)\n    at NZ (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:700:3921)\n    at file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:622:9014\n    at Q (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:526:17199)\n    at GX (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:622:8160)\n    at fS (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:622:7241)\n    at R9 (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:622:11408)",
    "timestamp": "2025-06-21T11:50:41.045Z"
  },
  {
    "error": "Error: Language not supported while highlighting code, falling back to markdown: \n    at aD (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:1184)\n    at file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:912\n    at Array.map (<anonymous>)\n    at kK (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:903)\n    at DU2 (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1865:7514)\n    at xE (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:80:19803)\n    at mT (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:42555)\n    at gT (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:38104)\n    at qq (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:38032)\n    at eE (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:37886)",
    "timestamp": "2025-06-21T12:08:36.514Z"
  },
  {
    "error": "Error: Language not supported while highlighting code, falling back to markdown: \n    at aD (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:1184)\n    at file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:912\n    at Array.map (<anonymous>)\n    at kK (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:903)\n    at DU2 (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1865:7514)\n    at xE (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:80:19803)\n    at mT (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:42555)\n    at gT (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:38104)\n    at qq (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:38032)\n    at eE (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:37886)",
    "timestamp": "2025-06-21T12:31:00.242Z"
  }
]

Alternatives Considered

Client-side name truncation: Would break tool functionality
Warning-only approach: Still allows broken configurations
Configuration validation: Doesn't help with runtime errors

Priority

Medium-High - This affects all users with complex MCP setups and significantly improves debugging experience.

Related Issues

General MCP debugging difficulties
User confusion about tool validation errors
Support burden for MCP configuration issues

Additional Context

Bug report submitted via /bug command with Feedback ID: ec6ed713-c23a-46e9-9ede-cba36b616643

View original on GitHub ↗

7 Comments

startakovsky · 1 year ago

GitHub Official Image with Docker MCP Toolkit and Claude 1.0.31 gives me this same error pictured below. Here is another issue same pain point.

This issue is nonexistent with Claude Desktop. How can I get around this?

CXwudi · 1 year ago

I found a workaround for GitHub MCP server, change the MCP server name to something shorter so that the tool name stays within 64 characters, for example, use gh instead of github:

"gh": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      },
      "type": "stdio"
    }

Then the longest tool would stay within 64 characters:

add_pull_request_review_comment_to_pending_review (gh)                                                               │
│                                                                                                                      │
│ Full name: mcp__gh__add_pull_request_review_comment_to_pending_review

can you test if the github mcp is working?

● I'll test the GitHub MCP by checking what GitHub functionality is available and then trying a simple operation.
  ⎿  {
       "login": "CXwudi",

ww2283 · 1 year ago

the workaround is great but defeat the purpose of using a single central maintained docker gateway mcp server approach. You have to separate the gh from the rest of the swarm.

On the other hand, I highly suggest removing of the prefix for mcp tools. I noticed that in Claude desktop, the tool calling of mcp servers are quite good, while in Claude Code, even with explicit mention of a tool name, CC often says cannot find that tool. This should be relevant to the extensive prefix added for a mcp tool.

startakovsky · 1 year ago

@ww2283 IMHO this is better stated as a bug in Claude Code rather than an enhancement request by framing it as a failure for the claude mcp add-from-claude-desktop command to work in certain situations and completely freezes up claude code. I have listed this issue here: https://github.com/anthropics/claude-code/issues/2445

ashwin-ant collaborator · 1 year ago

Tool names can now be up to 128 characters. Let me know if this works better!

startakovsky · 1 year ago

Tool names can now be up to 128 characters. Let me know if this works better!

Yes it does now. Thank you @ashwin-ant .

github-actions[bot] · 1 year ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Validation Error: Insufficient Context for Tool Name Length Constraint

Enhancement: Improve MCP tool validation error messages with server and tool context

Issue Type

Summary

Current Behavior

Proposed Enhancement

Enhanced Error Message (Example)

Implementation Benefits

Technical Approach

1. Enhanced Validation During Tool Loading

2. Smart Name Suggestions

3. Improved CLI Error Display

Use Cases

Environment Info

Related Error Logs

Alternatives Considered

Priority

Related Issues

Additional Context

7 Comments

Related Claude Code issues

Browse by topic