The tools field in a subagent's frontmatter is an allowlist. It names which tools the agent is allowed to use. If you leave it out, the agent inherits the usual set. If you list tools, the agent is limited to just those.
Why narrow the list
Matching tools to the job keeps a subagent honest. An agent meant only to read and report has no business editing files. If you give a review agent just Read, Grep, and Glob, it physically cannot change your code, so you can trust its output as a pure read of the codebase.
A read-only investigator
---
name: dependency-mapper
description: Traces how a module is imported and used across the codebase.
tools: Read, Grep, Glob
---
You map dependencies. Search for imports and usages of the target
module, then return a short list of files and how each one uses it.
Do not suggest changes.
A worker that can edit
When an agent needs to make changes, add the tools that let it act, plus the ones it needs to verify its work:
---
name: formatter-fixer
description: Fixes lint and formatting issues in changed files.
tools: Read, Edit, Bash
---
You fix formatting. Run the linter, apply fixes, and confirm the
check passes before reporting.
Pair it with permissions
The tools allowlist decides which tools exist for the agent. Your project permission rules still apply on top, so a Bash allowance is further shaped by any allow/deny patterns you have set. Give each agent the smallest set that lets it finish its job.
Comments
Be the first to comment.