Limiting Tool Access
Why Limit Tools at All?
Not every subagent needs every tool. Deliberately limiting tool access does two valuable things: it prevents unintended side effects (a reviewer literally can't modify your files), and it makes each subagent's role clearer when you have several of them. Think about what a subagent actually needs to do, and grant only that.
This is the principle of least privilege
Give a subagent the minimum tools required for its job — nothing more. A read-only researcher with no Edit/Write tool cannot accidentally corrupt your codebase, no matter what goes wrong in its reasoning. Constraint is a safety feature, not a limitation.
Tool Profiles by Subagent Type
Match the tool set to the job. These three profiles cover most subagents you'll build:
Three tool profiles: research (read-only), reviewer (+Bash to see changes), modifier (+Edit/Write to change code).
Allowlist vs. Denylist
You have two ways to express tool limits, and they compose. Use 'tools' as an allowlist when it's easier to name what's permitted; use 'disallowedTools' as a denylist when you want everything except a few. If both are set, the denylist applies first, then the allowlist resolves against what remains — a tool in both is removed.
# Reviewer: allowlist — needs Bash for git diff, but no Edit/Write
---
name: code-reviewer
description: Reviews code; use proactively after changes
tools: Read, Grep, Glob, Bash
---A reviewer needs Bash — but still not Edit
It's tempting to make a reviewer fully read-only, but it usually needs Bash to run git diff and identify pending changes. The key insight: grant Bash for inspection, but withhold Edit and Write so it can analyze without altering. Capability and restriction together.
The Four Pillars Together
Limiting tools is the fourth and final design pillar. Put all four together and a subagent stops being something that vaguely tries to help and becomes a focused, predictable worker:
- 1.Specific description — controls when the subagent launches AND what instructions it receives.
- 2.Structured output — the subagent knows when it's done and returns usable information.
- 3.Obstacle reporting — workarounds and quirks come back so the main thread doesn't rediscover them.
- 4.Limited tool access — only the tools the job needs: read-only for research, +Bash for reviewers, +Edit/Write only for modifiers.
Section complete
You can now design subagents that finish on time and report back clearly. The next section answers the strategic question: when do subagents actually help — and when do they get in the way?
Key Takeaways
- ✓Limiting tool access prevents unintended side effects and makes each subagent's role clearer — the principle of least privilege.
- ✓Three tool profiles cover most needs: research (Read/Grep/Glob), reviewer (+Bash for git diff, no Edit/Write), modifier (+Edit/Write).
- ✓A reviewer usually needs Bash to run git diff, but should still withhold Edit/Write — capability for inspection, restriction on changes.
- ✓Express limits with 'tools' (allowlist) or 'disallowedTools' (denylist); if both, denylist applies first, then allowlist resolves against the remainder.
- ✓Constraint is a safety feature: a read-only researcher cannot corrupt your codebase no matter what its reasoning does.
- ✓The four design pillars together — specific description, structured output, obstacle reporting, limited tools — turn a vague helper into a focused, predictable worker.
Check Your Understanding
Test what you learned in this lesson.
Q1.What two benefits come from limiting a subagent's tool access?
Q2.What tools does a typical code reviewer subagent need?
Q3.If a subagent sets both 'tools' (allowlist) and 'disallowedTools' (denylist), how do they combine?
Q4.What are the four design pillars of an effective subagent?
Practice This Lesson