chopshopr

Tool-boundary field note

If the agent can write, why do serious builders still start with read-only tools?

Because the first trust question is usually not whether the model is smart. It is whether the first side effect is cheap enough to let the workflow continue.

By Chopshopr 9 min read
Opinions If the agent can write, why do serious builders still start with read-only tools?
Contact Chopshopr

The embarrassing truth about agent products is that users do not first ask whether the model is brilliant. They ask whether the first side effect is safe. The primary sources now say this more directly than most demos do. MCP defines readOnlyHint, destructiveHint, and openWorldHint. OpenAI's tool-planning docs tell builders to separate read and write behavior. Developer mode treats tools without readOnlyHint as write actions, and the approvals guide keeps sensitive actions behind a pause. My inference from those sources, not their wording itself, is simple: dependable agents earn the second tool call by making the first one cheap to trust.

The thesis:

Serious builders start with read-only tools because adoption depends less on peak model intelligence than on the first side effect someone is willing to delegate.

The official tool stack already encodes this instinct

The MCP schema reference explicitly defines readOnlyHint, destructiveHint, and openWorldHint. The semantics are blunt: read-only means the tool does not modify its environment; destructive marks harder-to-reverse changes; open-world means the tool can touch external entities.

The MCP tools specification adds the interaction model around those hints. It says there should be a human in the loop with the ability to deny tool invocations, and it recommends clear indicators and confirmation prompts for operations. The same schema also warns that annotations are only hints and should not be trusted blindly from untrusted servers. In other words: capability labeling matters, but it does not replace actual boundaries.

OpenAI's current tool-planning guide reaches the same conclusion from a product-design angle. It tells builders to split operations when they have different permissions, safety risks, or confirmation requirements, and to separate read and write behavior so the model and the user can tell the difference.

Tool design choice Demo-first reading Dependable reading
One generic tool does everything Less schema work, more agent magic Harder to trust, confirm, and recover
Read-only tool Boring first move Cheap trust-building move
Destructive or public tool Real autonomy Needs a sharper boundary and review path
Open-world side effects The system feels connected The blast radius is finally visible

Read-only first changes the adoption math

OpenAI's developer mode guide says write actions require confirmation by default and that tools without readOnlyHint are treated as write actions. That is not a philosophical essay. It is a product behavior. The host assumes the first question is whether the action changes state.

The guardrails and approvals guide makes the human-review path even more explicit: the model can decide a sensitive action is needed, but the run pauses until someone approves or rejects it.

This is why dependable agents so often begin with verbs like list, show, health, doctor, search, or diff. A read-only first step buys the operator context without forcing a high-drama trust decision too early.

Isolation is the filesystem version of the same principle

The official Git worktree docs frame the mechanic plainly: one repository can support multiple working trees at the same time, and a linked or detached worktree is useful when you want experimental changes without disturbing current development.

That is the repo-shaped version of read-only first. Before the agent mutates the main surface, give the risky write path its own bounded lane. Inspect the current state, create the isolated worktree, run the build, and only then widen to push or deploy.

If the first tool is read-only but the second tool writes straight into a shared root, the system still has a trust problem. Isolation is how the write step earns its own proof surface.

What this means in Chopshopr's world

Local-first agent stacks are especially tempted to overreach because they feel private, fast, and close to the machine. That is exactly when serious builders should get more literal, not less literal. A local stack should surface the boring verbs first: doctor, health, list_models, search, grep, diff, screenshot.

The higher-consequence verbs can still exist. But they should be narrower and more explicit: deploy, send, delete, apply, archive, publish. Chopshopr's own worktree-first ship path is a good example of the idea. It does not claim the workflow is safe because an agent is smart. It narrows authority, adds a build gate, and forces the final proof step.

This is the real gap between demo magic and dependable tools. A demo wants the agent to act early so the audience feels the power. A dependable tool wants the operator to stay calm long enough to keep using it next Tuesday.

The practical build pattern

  • Split inspection verbs from mutation verbs at tool-design time.
  • Mark readOnlyHint, destructiveHint, and openWorldHint honestly.
  • Require approvals for consequential writes instead of hiding them behind one generic success flow.
  • Give repo-changing work a linked or throwaway worktree so the write path has its own boundary.
  • Make the proof surface legible: route, branch, task, revision, source link, or failing command.

Sources