How Delegation Works: The Description Drives Everything
The Description Is the Trigger
How does Claude decide to use a subagent at all? When you send a message, the name and description of every available subagent are included in the main agent's system prompt. The main agent reads those descriptions and matches your task to the most appropriate subagent. So the description is not documentation — it's the trigger that controls when a subagent launches.
The description does double duty
The description controls WHEN a subagent runs AND shapes WHAT it's told to do. When the main agent launches a subagent, it writes the task prompt — and it uses the description as guidance for writing that prompt. Tweaking the description steers both behaviors at once.
Automatic vs. Explicit Delegation
There are two ways a subagent gets used. Automatic: Claude matches your request to a subagent's description and delegates on its own. Explicit: you name the subagent in your prompt to guarantee it runs. To encourage automatic delegation, include phrases like 'use proactively' in the description.
The main agent reads every subagent's description and either auto-matches your task or honors an explicit by-name request.
How a Vague Description Hurts
Because the description shapes the task prompt, a vague description produces a vague delegation. Consider a code-review subagent. With a generic description, the main agent might write 'use git diff to find the current changes' — leaving the subagent to guess which files matter. If you instead add to the description 'You must tell the agent precisely which files to review,' the main agent now writes a specific prompt listing the actual files.
| Description quality | Task prompt the main agent writes | Subagent result |
|---|---|---|
| Generic ('reviews code') | 'use git diff to find changes' | Wanders, guesses which files matter |
| Specific ('tell the agent exactly which files') | 'Review src/auth/login.ts and session.ts' | Focused, reviews the right files |
The same subagent performs very differently depending on how its description steers the delegation prompt.
This technique generalizes. Adding 'return sources that can be cited' to a web-search subagent's description causes the main agent to include that instruction whenever it delegates. The description is your lever for controlling both triggering and task quality.
Making Delegation Reliable
- 1.Write a clear, specific description of when the subagent applies — this is what Claude matches against.
- 2.Add 'use proactively' (or similar) if you want Claude to delegate without being asked.
- 3.Include concrete example scenarios in the description to sharpen Claude's matching.
- 4.Bake task-shaping instructions into the description (e.g. 'specify exact files', 'return citations') so the delegation prompt comes out specific.
If your subagent isn't being used
The fix is almost always the description. Add more specific trigger scenarios and concrete examples so Claude understands exactly when to delegate. Vague descriptions are the #1 reason a subagent sits unused.
Next section
You understand the mechanics. Now let's get hands-on: creating your own custom subagents with the /agents command, starting in the next lesson.
Key Takeaways
- ✓Every available subagent's name and description are injected into the main agent's system prompt — the description is the trigger that controls when a subagent launches.
- ✓The description does double duty: it controls WHEN the subagent runs and SHAPES the task prompt the main agent writes for it.
- ✓Delegation is automatic (Claude matches your task to a description) or explicit (you name the subagent); add 'use proactively' to encourage automatic delegation.
- ✓A vague description yields a vague task prompt; a specific one (e.g. 'tell the agent exactly which files') yields a focused, reliable delegation.
- ✓Task-shaping instructions in the description (e.g. 'return citations') get carried into the delegation prompt automatically.
- ✓If a subagent isn't being used when expected, the fix is almost always a more specific description with concrete example scenarios.
Check Your Understanding
Test what you learned in this lesson.
Q1.How does the main agent decide which subagent to use?
Q2.Beyond triggering, what else does a subagent's description influence?
Q3.How do you encourage Claude to delegate to a subagent automatically?
Q4.A code-review subagent keeps reviewing the wrong files. What's the most effective fix?
Practice This Lesson