Subagents are a sharp tool. The mistake is using them for everything; the other mistake is never using them.
Use a subagent when
The output is noisy and you only want the conclusion. Searching a 200-file codebase for “where do we mint JWTs?” is going to read dozens of files. None of those reads belong in your main context. A subagent can do the search and hand back a paragraph.
You want to parallelize independent lookups. Three questions — “where is the email template defined?”, “where is the rate-limit config?”, “is there a feature flag for the new flow?” — can run as three subagents in one message. Five-second wait instead of fifteen.
You want a second opinion that hasn’t seen your reasoning. A code-review subagent that’s only seen the diff (not your conversation) gives independent feedback.
Don’t use a subagent when
You’ll need to iterate. Subagents return one message and exit. If you ask “find the bug” and get back “I think it’s in auth.ts:47,” you can’t follow up with “okay, why?”. You’re starting fresh.
The work is in your head, not the codebase. Design discussions, architecture choices, “should we use X or Y” — these need full context. Don’t subagent them.
A clean parallel call
In a single tool-call block:
Agent(description="Find email template", prompt="Where is the welcome-email template defined? Report path and a 3-line excerpt.")
Agent(description="Find rate-limit config", prompt="Where is the login rate limit set? Report file:line and the value.")
Agent(description="Find feature flag", prompt="Is there a feature flag for the new checkout flow? Report flag name and default.")Three results come back, each independent. Synthesize them in the main thread.
The honest cost
A subagent gets no context from your conversation. The prompt has to be self-contained — what to find, what shape the answer should take, what’s already been ruled out. Terse prompts produce terse, generic work. Treat the prompt like briefing a smart colleague who just walked into the room.