Custom subagents don't inherit MCP tools or ToolSearch — only get 6 hardcoded tools

Bug description

Custom subagents defined in ~/.claude/agents/ always receive exactly 6 tools (Read, Write, Edit, Bash, Glob, Grep) regardless of any frontmatter configuration. They do not receive:

• MCP tools (e.g. mcp__playwriter__execute)
• ToolSearch (needed to discover deferred MCP tools)
• Skill
• Agent / Task
• Any other tools listed in tools: frontmatter

Meanwhile, the built-in general-purpose agent correctly receives ToolSearch + Skill + core tools, and can successfully discover and call MCP tools via ToolSearch.

Environment

• Claude Code version: 2.1.81
• Platform: macOS (Darwin 24.6.0, arm64)
• Installation: Homebrew (/opt/homebrew/bin/claude)
• Model: Opus 4.6 (1M context)

Reproduction steps

1. Create a custom agent

~/.claude/agents/test-agent.md:

---
name: test-agent
description: Test agent for MCP tool access
model: sonnet
---

List all tools you have access to.

2. Spawn it and ask it to list tools

Use the test-agent to list all tools it has access to

Result: Agent reports only 6 tools: Read, Write, Edit, Bash, Glob, Grep.

3. Compare with general-purpose agent

Spawn a general-purpose agent (no subagent_type) with the same prompt.

Result: Agent reports 8 tools including ToolSearch and Skill.

4. General-purpose agent can load MCP tools; custom agent cannot

The general-purpose agent can call ToolSearch("playwriter"), load the MCP tool schemas, then successfully call mcp__playwriter__execute. Custom agents cannot because they lack ToolSearch entirely.

What was tested (all failed for custom agents)

| Approach | Result |
|---|---|
| tools: frontmatter with explicit MCP tool names | 6 tools only |
| tools: frontmatter omitted entirely (should inherit all per docs) | 6 tools only |
| disallowedTools: instead of tools: | 6 tools only |
| mcpServers: frontmatter referencing configured servers | 6 tools only |
| mcpServers: with inline server definitions | 6 tools only |
| permissionMode: bypassPermissions | 6 tools only |
| Various combinations of the above | 6 tools only |

Expected behavior

Per the subagent documentation:

"By default, subagents inherit all tools from the main conversation, including MCP tools."

Custom agents should inherit tools from the parent session the same way built-in agents do. At minimum, they should receive ToolSearch so they can discover deferred MCP tools.

Root cause hypothesis

It appears that custom agents loaded from ~/.claude/agents/*.md are spawned with a hardcoded tool set of 6 core tools. The tools: frontmatter field, disallowedTools: field, and mcpServers: field in the YAML frontmatter are not being processed — they have no effect on the actual tools available to the subagent at runtime.

The built-in agents (general-purpose, Explore, Plan) appear to use a different code path that correctly provides ToolSearch and other meta-tools.

Impact

This effectively makes MCP tools unusable from any custom subagent workflow, which is a significant limitation for users who have built agent hierarchies (orchestrators delegating to specialized agents). The only workaround is to use the general-purpose agent type and embed custom instructions in the prompt, losing the benefits of reusable agent definitions.

Related issues

• #25200 — Custom agents cannot use deferred MCP tools even when declared in mcpServers/tools frontmatter
• #13890 — Subagents unable to write files and call MCP tools silently
• #30280 — Sub-agents spawned via Agent tool don't reliably inherit MCP tools
• #37785 — MCP tools not available in spawned sub-agents via Agent tool