claude-code - 💡(How to fix) Fix Deferred MCP tools cause silent InputValidationError on first call — ToolSearch required but not enforced

Summary

When MCP tools are registered as deferred (only the tool name is known at session start, schema is lazy-loaded), calling one of these tools directly causes an InputValidationError because the parameter schema is not yet available. The workaround — calling ToolSearch("select:<tool_name>") first — is undocumented and non-obvious.

Steps to reproduce

1. Configure an MCP server whose tools are registered as deferred (e.g. a remote HTTP MCP server such as a custom Vercel-deployed MCP).
2. In a new Claude Code session, attempt to call one of those tools directly (e.g. mcp__my_server__wiki_list).
3. The call fails with InputValidationError — no schema available.
4. Call ToolSearch("select:mcp__my_server__wiki_list") to hydrate the schema.
5. Call the same tool again — now it succeeds.

Expected behavior

Either:

• Option A: Claude Code automatically hydrates deferred tool schemas on first use (transparent to the model and user), OR
• Option B: The system prompt / tool documentation clearly states that ToolSearch must be called before any deferred tool.

Currently neither is the case. The model sometimes skips the ToolSearch step (because it "knows" the tool name from context), which causes a first-call failure followed by a retry — wasting a round trip and confusing the user.

Actual behavior

• First call → InputValidationError (schema not loaded)
• Model calls ToolSearch to load schema
• Second call → success

From the user's perspective this looks like a random transient error on every new session.

Environment

• Claude Code (Claude Agent SDK, CLI / web)
• MCP tools registered as deferred (lazy-loaded schemas)
• Observed consistently across multiple sessions with HTTP MCP servers

Suggested fix

Auto-hydrate deferred tool schemas when a model attempts to call them, rather than requiring an explicit ToolSearch preflight. If lazy-loading is intentional for performance, emit a clear system-level warning when a deferred tool is called without its schema loaded, and auto-insert the ToolSearch step transparently.

Reported via Claude Code session — user-facing symptom: "Warum gibts beim ersten bash und toolsearch immer einen Fehler?" (Why does the first bash/toolsearch always produce an error?)