# Choosing tools

Every agent is granted exactly one named tool collection. The collection is the
single most important safety decision you make, because it is the boundary
between an agent that can only *look* and one that can *change things*. Pick the
narrowest collection that still lets the agent finish its job.

## The three collections

There are three, and they nest:

- **`read-only`** — the agent can observe but never mutate. It reads files,
  lists directories, greps and finds across the workspace, searches the web, and
  fetches pages. Nothing it does leaves a mark on the workspace.
- **`coding`** — everything in `read-only`, plus the mutating and stateful
  tools: writing and editing files, running shell commands, managing a running
  process, and keeping a todo list. This is the working engineer's surface.
- **`all`** — every registered tool. In practice this equals `coding` today, but
  it is the right choice when you mean "whatever exists," not a fixed set.

## How to choose

Ask one question: *does this agent need to leave the workspace different than it
found it?* If the answer is no, use `read-only` and stop. A researcher, a
reviewer, a summariser, a question-answerer — none of them should be holding the
write tool. Granting more access than the task needs does not make the agent
more capable; it just widens the blast radius of a mistake.

If the agent genuinely has to produce edits, run a build, or drive a process,
use `coding`. Reach for `all` only when you specifically want the agent to pick
up tools that get registered later without you having to revisit the blueprint.

## Read-only is a real guarantee

It is worth saying plainly: read-only is not a hint to the model, it is the set
of tools the agent is *handed*. An agent on the `read-only` collection has no
write, edit, or bash tool to call, so it cannot mutate the workspace even if its
prompt drifts or it is asked to. That is exactly why you should default to it.
Promote to `coding` deliberately, as an explicit decision, not because it seems
convenient.

## Match the collection to the prompt

A mismatch between the prompt and the collection is a common and confusing bug.
If the system prompt tells the agent to "edit the file and re-run the tests" but
the collection is `read-only`, the agent will flail trying to call tools it does
not have. Keep the two in sync: a read-only agent's prompt should describe a
read-only job, and a coding agent's prompt should acknowledge that its edits are
real.
