[DOCS] Contradictory information regarding MCP tool availability in Subagents

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

The interaction between the "Available tools" section and the "Run subagents in foreground or background" section.

Current Documentation

In the Available tools section:

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

However, in the Run subagents in foreground or background section:

"MCP tools are not available in background subagents."

What's Wrong or Missing?

The documentation presents a direct contradiction. The "Available tools" section implies that MCP tools are always inherited and usable by subagents. However, the background execution section clarifies that this is not true for background processes.

Because Claude Code often automatically decides whether to run a subagent in the foreground or background, a developer reading only the "Available tools" section might design a subagent that relies on MCP tools, only to encounter non-deterministic failures if Claude chooses to run that agent in the background.

Suggested Improvement

The "Available tools" section should be updated to immediately flag this limitation.

Suggested text for "Available tools":

"By default, subagents inherit all tools from the main conversation, including MCP tools. Note: MCP tools are only available when the subagent runs in the foreground. If the subagent runs in the background, MCP tools will be unavailable."

Impact

High - Prevents users from using a feature

Additional Context

This ambiguity creates a trap for developers: if they create a subagent specifically to use an MCP tool (e.g., to query a database via MCP), it may work during testing (if running in foreground) but fail in production usage if Claude decides to background the task. Explicitly linking these constraints in the definition section is crucial for designing robust agents.