A subagent is a separate context with its own instructions, its own tools, and often its own model — useful precisely because what it reads does not end up in the main conversation. Two fields decide whether it earns that separation. The description is what causes work to be delegated to it, and it competes with every other agent you have defined, so a vague one either never fires or fires constantly. The tool list is the cheapest way to keep a narrow agent narrow: an agent that can only read and search cannot wander off and start editing. This builder writes the file and checks both, including the combination that catches people out — write access without read access.
Features
Description checked for the clause that causes delegation
Tools picked from the real list rather than typed from memory
Namespaced MCP tools accepted alongside the built-in ones
Warns when an agent can write files but not read them
Model choice explained in terms of when each one is worth it
Project or personal scope, with the matching path
An inherited model is omitted rather than written out
Downloads as a ready-to-use .md file
How to use the Subagent Builder
Name the agent and say when work should be handed to it
Pick the tools it needs — and only those
Choose a model, or leave it inheriting the session's
Write the system prompt, then download the file
Example
Input
tools: [Read, Grep, Glob]
Output
description: Checks a database migration for problems that only show up in production. Use proactively whenever a migration file is added.
“Use proactively when…” is what makes an agent fire without being asked.
Common errors & troubleshooting
The agent is never delegated to. — The description has to say when, not just what. Adding “Use when…” or “Use proactively after…” is usually the whole fix.
Two agents keep getting confused with each other. — Their descriptions overlap. Make each one name a distinct situation rather than a distinct subject.
A tool name is flagged as unknown. — Tool names are case-sensitive and capitalised — Read, not read. MCP tools use the mcp__server__tool form and are accepted as written.
The agent edits things I did not expect. — Give it a narrower tool list. An agent with no Write or Edit cannot change anything, whatever its prompt says.
Frequently asked questions
When is a subagent better than doing the work inline?
When the work involves reading a lot to produce a little — searching a codebase, checking many files, researching — because everything it reads stays in its own context. It is also the way to run a narrower tool set than the main session has.
Which model should a subagent use?
Inheriting is a fine default. A cheaper, faster model is worth choosing for mechanical passes where the work is checking rather than deciding; a more capable one for work that needs judgement. The trade-off is described next to each choice.
Should I always restrict the tools?
Restricting is cheap and reversible, and it is the most reliable way to keep a focused agent focused — far more so than telling it not to do things in the prompt. Leaving the list empty inherits everything, which is fine for general-purpose agents.
Project scope or personal scope?
Project scope commits the agent with the repository, so everyone working on it gets the same one. Personal scope follows you across projects. The path updates as you choose.
How is this different from a skill?
A skill adds instructions to the current context. A subagent runs somewhere else, with its own context and its own tools, and reports back. Use a skill to change how something is done; use a subagent to keep the doing of it out of your conversation.
Related tools
Skill Builder — Write a SKILL.md with the frontmatter checked as you type.
Slash Command Builder — Build a custom slash command, with arguments and a tool allow-list.
Permission Rule Tester — Test allow, ask and deny rules against real commands before you trust them.
Hooks Builder — Build settings.json hooks and catch the matchers that never fire.