Descriptions That Shape Input Prompts
A Recap With New Depth
You already know the description triggers delegation. The deeper point for DESIGN is this: the description also shapes the input prompt the main agent writes when it launches the subagent. So one field controls two behaviors — when the subagent runs, and what it's told to do. Getting the description right is the highest-leverage design move you can make.
The description is one field with two jobs: it triggers delegation AND steers the task prompt the main agent writes.
Vague In, Vague Out
Watch the mechanism on a code-review subagent. With a generic description, the main agent might write a task prompt like 'use get diff to find the current changes.' That's vague — the subagent has to figure out which files matter on its own, and often reviews the wrong things or wanders.
Now update the description to include: 'You must tell the agent precisely which files you want it to review.' The main agent reads that and writes a much more specific input prompt — one that lists the actual files. Same subagent, same code, dramatically better result, all from a one-line description change.
| Description | Input prompt the main agent writes | Outcome |
|---|---|---|
| 'Reviews code changes' | 'use git diff to find the current changes' | Subagent guesses which files matter |
| '...tell the agent precisely which files to review' | 'Review auth/login.ts and auth/session.ts' | Subagent reviews exactly the right files |
The description is upstream of the input prompt — so vague descriptions guarantee vague delegations.
The Technique Generalizes
This isn't specific to code review. Any instruction you bake into the description gets carried into the delegation prompt. The pattern: 'whatever you want the main agent to always tell this subagent, put it in the description.'
- •Web-search subagent: add 'return sources that can be cited' → the main agent instructs it to cite sources every time.
- •Test-writer subagent: add 'specify the exact module and the framework in use' → delegations name the target module and test framework.
- •Migration subagent: add 'state the source and target versions explicitly' → the task prompt always carries the version pair.
Design descriptions as instructions to the orchestrator
Stop thinking of the description as 'what this agent is' and start thinking of it as 'what I want the main agent to say when it hands off.' That reframing turns the description into a precise control surface for delegation quality.
Putting It to Work
A strong description does four things at once: states when to delegate (trigger), includes 'use proactively' if you want automatic delegation, embeds concrete example scenarios so matching is reliable, and bakes in task-shaping instructions so the input prompt comes out specific.
---
name: code-reviewer
description: Expert code review specialist. Use proactively after code
changes. You must tell the agent precisely which files to review and
ask it to return findings grouped by severity.
tools: Read, Grep, Glob, Bash
---Next
A well-shaped input gets the subagent started right. The next lesson covers the single most important thing for getting it to FINISH right: a defined output format.
Key Takeaways
- ✓For design, the key fact is that the description shapes the input prompt the main agent writes — not just whether the subagent runs.
- ✓A vague description ('reviews code') yields a vague delegation; a specific one ('tell the agent precisely which files') yields a focused task prompt.
- ✓Any instruction baked into the description is carried into the delegation prompt (e.g. 'return sources that can be cited').
- ✓Reframe the description as 'what I want the main agent to say at hand-off' — a control surface for delegation quality.
- ✓A strong description does four jobs: trigger, 'use proactively' for automatic delegation, concrete examples, and task-shaping instructions.
- ✓This is the highest-leverage design move because it fixes both when the subagent runs and how well it's instructed.
Check Your Understanding
Test what you learned in this lesson.
Q1.Beyond triggering delegation, what does a subagent's description shape?
Q2.A reviewer subagent keeps guessing which files to review. Which description change fixes it best?
Q3.How do you make a web-search subagent always return citable sources?
Q4.What's the most useful mental reframe for writing a subagent description?
Practice This Lesson