fix: teach agents the ToolSearch deferred-tool step (heavy-MCP sessions)#20
Merged
Conversation
…sions In sessions with many MCP servers connected, Claude Code defers MCP tools: the tool name is shown but its schema is not loaded, and a direct call fails until the caller materializes it via ToolSearch. The five Gemini agents told themselves to "use the gemini_search_grounded tool" but never mentioned ToolSearch, so a subagent in a heavy-MCP session could not find a directly callable Gemini tool, burned its turn budget hunting for the name, and ended mid-investigation without emitting its JSON. The orchestrator then fell back to plain web search. Intermittent because a light session loads the tools directly and a capable model sometimes rediscovers ToolSearch unaided. Distinct from the v0.4.1 tools:-allowlist bug and from the stale-session case gemini-doctor covers. - Add a "Deferred tools (do this FIRST)" step to each agent's Tool availability section: ToolSearch with a namespace-agnostic keyword query, then call the exact tool name returned; treat as missing only after ToolSearch returns no match. - gemini-consult skill documents the path and points to gemini-doctor. - tests/mcp-namespace.bats asserts every agent documents the ToolSearch step via a keyword query (not a hardcoded mcp__ path). 83 tests pass. - Bump to 0.5.1; CHANGELOG updated.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Root cause (reproduced empirically this time)
When many MCP servers are connected, Claude Code switches MCP tools into deferred mode: the tool name is shown in a system reminder but its schema is NOT loaded, so a direct call fails with an input-validation error until the caller materializes it via
ToolSearch.The five Gemini agents instructed themselves to "use the
gemini_search_groundedMCP tool" but never mentionedToolSearch. So a subagent in a heavy-MCP session could not find a directly-callable Gemini tool, "hunted for the tool name," burned its turn budget, and ended mid-investigation without emitting its JSON. The orchestrator then fell back to plain web search. This matches the user's reports exactly:Evidence
mcp__plugin_gemini-plugin_gemini__gemini_search_grounded(afterToolSearch)gemini-researcheron a German-law questionconfidence: highToolSearchtools:allowlist (v0.4.1 fix present), and none mentionToolSearchThis is a third, distinct cause, separate from the v0.4.1
tools:-allowlist bug and from the stale-session casegemini-doctoralready covers. It is intermittent because a light session loads the tools directly, and a capable model sometimes rediscoversToolSearchunaided (which is why it "sometimes works").Fix
**Deferred tools (do this FIRST)**step to the "Tool availability (fail loud)" section — callToolSearchwith a namespace-agnostic keyword query (e.g.gemini search grounded), then call the exact tool name returned; treat the tool as missing ONLY afterToolSearchreturns no Gemini match. Keyword queries match both install namespaces and contain nomcp__token, so the existing no-hardcoded-namespace test stays green.gemini-consultskill: documents the deferred-tool path and routes to/gemini-plugin:gemini-doctorwhen an agent returnsunavailable/unknownwith a missing-tool error.tests/mcp-namespace.bats: two new guards — every agent must mentionToolSearch, and must use a keyword query (not a hardcodedmcp__path).Verification
bats tests/→ 83 passed, 0 failed (added #72, #73). No em/en dashes in the diff.Release
After merge, tag
v0.5.1to let the new release workflow (#19) publish it.