Teammate agents cannot see ToolSearch in their visible tool list

Resolved 💬 5 comments Opened Feb 6, 2026 by alkautsarf Closed Mar 20, 2026

Bug Description

When spawning teammate agents (via agent teams), ToolSearch does not appear in the agent's visible tool list, even though it is callable and works perfectly when invoked directly.

This causes agents to:

  1. Read the instruction "call ToolSearch to load MCP tools"
  2. Check their available tool list
  3. Not see ToolSearch listed
  4. Conclude the instruction is wrong
  5. Spiral into alternatives (Grep, Skill, Bash, Task delegation)

Steps to Reproduce

  1. Enable agent teams: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  2. Enable tool search: ENABLE_TOOL_SEARCH=true
  3. Spawn a teammate agent (plugin-defined or general-purpose)
  4. Ask the teammate to list its available tools — ToolSearch is not listed
  5. Ask the teammate to call ToolSearch anyway — it succeeds

Expected Behavior

ToolSearch should appear in the teammate agent's visible tool list, just like Read, Bash, Edit, and other built-in tools.

Actual Behavior

ToolSearch is hidden from the tool list but IS callable. The agent has to "trust" that ToolSearch exists without seeing it, which conflicts with how models reason about available tools.

Diagnostic Evidence

Spawned two teammate agents (Opus) and asked them to report their tools:

  • kairos-debug initially reported: "ToolSearch is NOT available to me as a teammate agent"
  • gp-debug listed 23 tools — ToolSearch not among them
  • When explicitly told to "just try calling ToolSearch", both agents succeeded on the first attempt with zero errors
  • All 3 ToolSearch calls loaded MCP tools correctly

The agent corrected itself: "ToolSearch DOES work for teammate agents. My initial report was wrong — I inferred without actually trying."

Workaround

We instruct agents to call ToolSearch as their absolute first action with explicit guidance: "ToolSearch will NOT appear in your tool list. Call it anyway — it works. Do not check your tools first."

Environment

  • Claude Code version: 2.1.34
  • OS: macOS (Darwin 25.1.0)
  • Plugin: pragma (custom plugin with MCP server)
  • ENABLE_TOOL_SEARCH: "true" in settings
  • CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" in settings

View original on GitHub ↗

This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗