toolcall() ← all concepts

// concept · agents

Your subagent doesn't know what you know.

It shares the same machine and the same files, and none of your conversation. So it starts from nothing but the message you sent it, goes and finds out what you already knew, and answers confidently.

// same machine, different conversation

Agents in a multi-agent setup share more than people expect and less than people assume. Anthropic's guidance draws the line precisely:

All agents share the container and filesystem; each runs in its own thread — a context-isolated event stream with its own conversation history, model, system prompt, tools, MCP servers, and skills.

And then names the trap it creates:

Don't assume shared context. Threads share the filesystem but not conversation history or tools. If the coordinator needs a subagent to act on something, it must say so in the delegated message (or write it to disk).
# what it can reach the same files yes the same conversation no # so what it actually starts with your message ■■■■ everything else (empty)

That isolation is the point

It would be easy to read the above as a defect. It is the opposite — it is the entire reason delegating scales:

Each delegated piece runs in its own thread with a fresh context window, threads run in parallel in the same container, and only each subagent's report comes back, so the coordinator's context stays small.

A subagent is not less capable than you. It is less informed, on purpose, and the report coming back instead of the whole investigation is what you are buying. The trade is simply that the brief is now the entire context.

What a thin brief actually costs you

Get the brief wrong and you lose both halves of that trade. The guidance is direct about the overhead:

Subagents multiply cost and time: each one re-establishes context, re-explores, and reports back, and you then re-read its report. Delegate rarely and only when the payoff clearly exceeds that overhead.

So it opens the same files you already opened. It hits the same dead ends you already ruled out. It works out the thing you worked out an hour ago — all because none of that was in the message. And then it answers the question you literally sent rather than the one you meant, and it does so confidently, which is what makes the report easy to accept.

That is the failure mode worth naming: not a crash, not an obvious error, but a good-looking answer built on a context that was missing the thing that mattered.

When to hand it over, and when not to

The guidance is unusually concrete here, so it is worth quoting rather than paraphrasing.

Do:

Large tasks that are genuinely independent and parallelizable. For example, wide multi-file investigations.

Do not:

Work you could finish yourself in a handful of tool calls... Review, verification, or to double check your work. Verification belongs in your main agent loop.

The first is intuitive once you see the round-trip cost — "a small single-step task" is a poor fit because "every delegation costs a round-trip and a re-briefing."

The second is the one that catches people, because handing your work to a fresh pair of eyes feels like the responsible move. It never saw the reasoning it is supposed to be checking. It sees an artifact and a sentence, and it will tell you the artifact looks fine.

And one more, cheap to follow and easy to skip: "Brief the subagent precisely the first time. Avoid launching, waiting, and re-briefing." Re-briefing pays the round trip twice.

The practical version

Before you split a task, write the message you would send and ask what it assumes. If the answer includes a file you have open, a decision you made earlier, or a constraint you have been carrying in your head, that assumption is about to be silently dropped — so either put it in the message or write it to disk where the subagent can reach it.

There is deliberately no number here for how many agents is right. Recommendations that name a figure are tied to a specific model's prompt, not to the architecture.

Sources: Anthropic agent-design and multi-agent orchestration guidance (shared/agent-design.md, shared/managed-agents-multiagent.md). Related: why the model is stateless in the first place · whether you needed an agent at all · parallel tool calls inside one agent.

One concept a week. Free.

The deeper, copy-paste version of each ToolCall short — in your inbox.

// total: 0.00 · spam: void · unsubscribe: one click