[BUG] Misleading "No such tool available" error when MCP tool called with invalid parameters

[bugok]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When calling an MCP tool with incorrect parameter names, Claude Code returns a misleading error message: Error: No such tool available: mcp__XXXX__knowledge_load

This suggests the MCP server isn't connected or the tool doesn't exist, when in reality the tool does exist but was called with the wrong parameter name (e.g., uri instead of url).

What Should Happen?

The error should clearly indicate that the tool exists but was called with invalid parameters: Error: Invalid parameters for tool 'mcp__XXXX__knowledge_load' Expected parameters: url, start_creation_time, end_creation_time Provided parameters: uri Parameter 'uri' is not valid. Did you mean 'url'?

Error Messages/Logs

Error: No such tool available: mcp__XXXX__knowledge_load

Steps to Reproduce

1. Set up an MCP server with a tool that has specific parameter requirements (e.g., knowledge_load tool expecting url parameter)
2. Call the tool with an incorrect parameter name: mcp__XXXX__knowledge_load(uri="https://example.com/...")
3. Instead of: mcp__XXXX__knowledge_load(url="https://example.com/...")
4. Observe the error: "No such tool available: mcp__XXXX__knowledge_load"
5. Run diagnostics to verify MCP server is connected and tool is registered - confirming the error message is misleading

Root Cause Analysis

Based on the compiled CLI code at /usr/local/bin/claude_code/node_modules/@anthropic-ai/claude-code/cli.js, the tool lookup logic appears to fail during parameter validation, returning null when the tool schema doesn't match, which triggers the "No such tool available" error path.

The issue is in the tool execution flow where:

1. Tool lookup happens with parameter validation
2. If parameters don't match schema, lookup returns null
3. Null result triggers "No such tool available" error
4. Actual validation error is never surfaced to the user

Suggested Fix

The tool execution logic should:

1. Separate tool lookup from parameter validation - First check if tool exists by name
2. Then validate parameters separately - Parse input schema and provide specific validation errors
3. Include helpful context - Show expected vs provided parameters, suggest corrections

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.0.57

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Other

Additional Information

This issue impacts debugging MCP tool integrations because:

1. Developers waste time checking MCP server connections when the real issue is parameter naming
2. The error suggests a configuration problem rather than a usage problem
3. No actionable information is provided to fix the call

The fix would improve development experience for all MCP tool users by providing clear, actionable error messages similar to TypeScript's parameter validation errors.