Validation Error: Insufficient Context for Tool Name Length Constraint

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

1. Client-side name truncation: Would break tool functionality
2. Warning-only approach: Still allows broken configurations
3. 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