Subagent prompting and tool scoping

How you brief a subagent, and what you let it touch.

4 min read · Lesson 7 of 12 in this domain

Two levers decide whether a subagent is useful: what you tell it, and what you let it touch. On the first, there is a real tension — precise instructions feel safer, but they are exactly what makes an agent brittle, because a script that meets an unanticipated situation has nowhere to go. Delegating intent plus a quality bar lets the subagent adapt when the first approach fails. On the second, the instinct to hand over every tool "just in case" is a mistake twice over: it widens what a mis-selection can damage, and a larger tool surface measurably degrades selection accuracy.

• Over-specified procedural instructions (exact queries, exact filters) make subagents brittle — when the script fails they report failure instead of adapting.
• Prefer goal-oriented prompts: state the research intent, the minimum quality bar, and source-credibility criteria. That grants authority to adapt.
• Scope tools by role. A research subagent should not hold deploy or delete tools. Universal tool access is a named anti-pattern — it widens the blast radius and degrades selection accuracy.
• Subagent failures must return structured error context, never an empty result. An empty result is indistinguishable from "searched and found nothing", so the coordinator draws a false conclusion.
• Brief precisely the first time. Launch → wait → re-brief cycles cost more than getting the brief right.

Source: Claude Docs — Agent SDK subagents · Independent study aid, not affiliated with or endorsed by Anthropic.