Skip to content

fix: teach agents the ToolSearch deferred-tool step (heavy-MCP sessions)#20

Merged
azmym merged 1 commit into
mainfrom
fix/deferred-mcp-tool-toolsearch
Jun 1, 2026
Merged

fix: teach agents the ToolSearch deferred-tool step (heavy-MCP sessions)#20
azmym merged 1 commit into
mainfrom
fix/deferred-mcp-tool-toolsearch

Conversation

@azmym

@azmym azmym commented Jun 1, 2026

Copy link
Copy Markdown
Owner

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_grounded MCP tool" but never mentioned ToolSearch. 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:

  • the researcher "was still hunting for the gemini_search_grounded tool name"
  • "the Gemini grounded-search tools aren't reachable from my toolset"

Evidence

Test Result
Direct call to mcp__plugin_gemini-plugin_gemini__gemini_search_grounded (after ToolSearch) ✅ real answer + citations — server is healthy
Real installed gemini-researcher on a German-law question ✅ grounded JSON, confidence: high
Generic subagent probe ❌ tool "NOT directly callable, appeared only in the deferred-tools list, schema not loaded"; ✅ became callable after ToolSearch
Disk audit installed v0.5.0 agents have no tools: allowlist (v0.4.1 fix present), and none mention ToolSearch

This is a third, distinct cause, separate from the v0.4.1 tools:-allowlist bug and from the stale-session case gemini-doctor already covers. It is intermittent because a light session loads the tools directly, and a capable model sometimes rediscovers ToolSearch unaided (which is why it "sometimes works").

Fix

  • All 5 agents: added a **Deferred tools (do this FIRST)** step to the "Tool availability (fail loud)" section — call ToolSearch with a namespace-agnostic keyword query (e.g. gemini search grounded), then call the exact tool name returned; treat the tool as missing ONLY after ToolSearch returns no Gemini match. Keyword queries match both install namespaces and contain no mcp__ token, so the existing no-hardcoded-namespace test stays green.
  • gemini-consult skill: documents the deferred-tool path and routes to /gemini-plugin:gemini-doctor when an agent returns unavailable/unknown with a missing-tool error.
  • tests/mcp-namespace.bats: two new guards — every agent must mention ToolSearch, and must use a keyword query (not a hardcoded mcp__ path).
  • Bumped to 0.5.1; CHANGELOG updated.

Verification

bats tests/83 passed, 0 failed (added #72, #73). No em/en dashes in the diff.

Release

After merge, tag v0.5.1 to let the new release workflow (#19) publish it.

…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.
@azmym azmym added the Claude_Code Changes made by Claude Code label Jun 1, 2026
@azmym azmym self-assigned this Jun 1, 2026
@azmym
azmym merged commit ea9328d into main Jun 1, 2026
2 checks passed
@azmym
azmym deleted the fix/deferred-mcp-tool-toolsearch branch June 1, 2026 12:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Claude_Code Changes made by Claude Code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant