Long agent_prompt suppresses parallel tool calling in Claude Code harness

[greynewell]

Summary

During mcpbr experiments, we discovered that verbose agent_prompt configurations (19-20 lines with numbered workflow steps) effectively suppress parallel tool calling behavior in the Claude Code agent harness, even when tools have readOnlyHint: true annotations.

Evidence

Analysis of 28+ mcpbr experiment runs across .mcpbr_run_* directories:

Run	Prompt length	Parallel turns	Total turns	Parallel %
20260207_214727	No prompt	108	11,919	0.9%
20260209_170925	~5 lines	15	60	25.0%
20260209_170209	~5 lines	6	60	10.0%
20260212_144524	19 lines	1	259	0.4%
parallel_trial	20 lines	0	150	0.0%

Runs with no prompt or short prompts (≤5 lines) achieved 0.9-25% parallel tool call rate, while runs with verbose prompts (19-20 lines containing numbered workflow instructions) achieved 0-0.4%.

Hypothesis

The structured, numbered workflow steps in long prompts (e.g., "1. EXPLORE... 2. STOP EXPLORING... 3. FIX... 4. TEST...") may cause the model to follow a rigid sequential pattern, overriding its natural tendency to parallelize independent tool calls. The explicit step-by-step instructions create a mental model of sequential execution even when tools are marked as safe for parallel use.

Reproduction

1. Run mcpbr with a verbose agent_prompt containing numbered workflow steps (19+ lines)
2. Run mcpbr with no agent_prompt or a minimal one (≤5 lines)
3. Compare parallel tool call rates in the output logs

Search for parallel calls with: count assistant messages containing multiple tool_use content blocks.

Impact

This affects SWE-bench evaluation speed and turn efficiency. Parallel tool calls allow exploring multiple symbols simultaneously, reducing the number of turns needed before the agent starts coding.

Potential solutions

• Keep agent prompts minimal (≤5 lines) — let the MCP server instructions handle workflow guidance
• Avoid numbered step-by-step instructions in agent prompts
• Use the MCP server's instructions field (which doesn't seem to suppress parallelism) instead of agent_prompt for workflow guidance
• Further experimentation needed to isolate which specific prompt patterns cause suppression

[greynewell]

Updated findings from trial runs

Ran a controlled trial comparing the minimal 3-line prompt (PR #124) vs the verbose 20-line prompt:

Run	Prompt	Parallel turns	Total turns	Rate
Minimal prompt	3 lines	23	202	11.4%
Verbose prompt	20 lines	0	129	0.0%
Historical (short)	~5 lines	15	60	25.0%
Historical (none)	0 lines	108	11,919	0.9%

The minimal prompt restores parallel tool calling from 0% to 11.4%. Confirmed.

Important nuance: MCP tools are NOT being parallelized

Across all runs, the parallelism is almost exclusively native Claude Code tools (Read, Grep, Bash, Glob). MCP tools (mcp__supermodel__symbol_context) are called in parallel in only 5 out of 12,000+ turns total.

This means:

• readOnlyHint: true doesn't drive MCP tool parallelism in practice with Sonnet 4
• The batch symbols parameter is the right approach for multi-symbol lookup (single call, multiple results)
• The prompt length primarily affects native tool parallelism, which is still valuable for overall agent efficiency

[m13v]

this is a really interesting finding and matches what we've observed running parallel Claude Code agents daily. the numbered step pattern is basically teaching the model to think sequentially even when it doesn't need to.

we found a similar effect with CLAUDE.md files - long detailed workflow instructions in the project config reduced tool parallelism compared to keeping instructions minimal and letting the model figure out the execution order. our workaround was moving most of the workflow detail into individual tool descriptions instead, which seems to stay out of the model's planning loop.

the MCP tool parallelism gap is surprising though. we use MCP heavily for desktop automation and the model almost never batches those calls even when they're clearly independent (like reading two different UI elements). feels like the harness might be treating MCP tools differently from native ones at the scheduling level.

[m13v]

we run multiple Claude agents in parallel using tmux orchestration and this prompt length effect was a real bottleneck until we restructured. our orchestration setup that manages parallel agents is documented here: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md