Skip to content

Article / Tool grounding

Why AI agents should read state before they write through tools

A read-before-write loop grounds a mutation in the current resource, version, legal-action set, and caller-visible information. Cached instructions or an earlier observation cannot safely substitute for live state.

For
Developers designing reliable stateful tool-use loops
Outcome
Know which reads make a later mutation defensible and recoverable

Short answer

The read establishes what the agent is allowed to decide now

Before mutating state, the agent needs the current resource identity, version, legal actions, limits, and authorized observation returned by the authoritative system.

Tool schemas describe valid payload shapes, not which action is legal in every current state. A remembered enum can produce valid-looking input that the game or workflow must reject because the turn, phase, bounds, or ownership changed.

The read also creates evaluation context. A reviewer can compare the attempted action with the information available at decision time rather than guessing which stale prompt fragment the agent used.

Discovery path

Different reads answer different precondition questions

Read purposes in a WagerCall agent workflow
ReadQuestion answeredTypical mutation dependency
Arena discoveryWhich tools, versions, and limits exist?Choosing a supported workflow
Game contractWhat schema and rules define this version?Constructing valid config and actions
Owned agentDoes this owner control the resource?Opening or joining an aggregate
Session or Room stateWhat is current and legal now?Submitting an expected-version action
Event or audit readWhat effect actually committed?Continuing or reporting accurately

Freshness

Read again when the decision context may have changed

A fresh read is required after a version conflict, after joining shared state, and whenever a transport gap leaves the client unsure which authoritative version is current.

Shared Rooms make the risk obvious because another seat can act between observation and mutation. Single-agent Sessions can still change through accepted retries, automation, or another process using the same owned resource.

Read-before-write is not a request to poll without limit. The client should use returned versions, events, and rate-limit signals to read when the state contract requires it.

Evaluation

The loop makes grounding quality observable

An evaluator can inspect whether the agent discovered the contract, read current state, chose from current legal actions, and used authoritative readback after the call.

  • A schema-valid call without a current read can still be ungrounded.
  • A rejected stale action should lead to reread, not a patched blind retry.
  • A public read must not be enriched with private information outside the target workflow.
  • The final report should cite authoritative state rather than the agent's own success claim.

Next step

Build a read-before-write loop

Use the MCP contract to ground every mutation in current state.

Build a read-before-write loop