Bounded agent tools

Introduce a write tool behind a bounded cohort

Moving from suggestions to mutations changes the product's responsibility. Release one explicit operation with observable effects and a way to stop it.

In this article

Keep the first capability narrow

Choose a mutation with a clear eligibility rule and a manageable recovery path. Adding a delivery note to an open order is easier to constrain than exposing a general order editor. Define the permitted fields, target scope and approval requirements before connecting the model.

Test the executor independently, including stale state, duplicate requests and unauthorised targets. These checks should already work when the model integration begins. A rollout cohort is not a substitute for missing access controls.

Document which service identity performs the change and why its permissions are sufficient. Avoid using an administrator credential simply because it makes the initial integration easier.

Observe proposals before enabling effects

Where useful, run a proposal-only phase. Compare the generated target and payload with what a reviewer expects, but ensure this mode cannot accidentally call the write endpoint. Label its results accurately because a good proposal does not prove reliable execution.

Use the phase to find ambiguous user requests and unsupported order states. Improve the tool contract or request clarification rather than teaching the model to guess more confidently.

Keep the evaluation data representative of the intended cohort. A small set of unusually clean examples will not reveal ordinary mismatched identifiers or incomplete instructions.

Enable a limited execution path

Restrict the initial rollout by authenticated audience, operation and target scope. Observe policy denials, uncertain results, duplicate effects and the time operators spend recovering runs. Check actual business records alongside conversational output.

Provide a capability switch that prevents new mutations. Define separately what happens to accepted or in-flight operations when it is used. Removing a tool from future prompts does not cancel work already queued.

Set expansion criteria before reviewing the results. Include useful completion, recovery behaviour and the absence of prohibited effects. Do not expand solely because users like the assistant's wording.

Retain a practical rollback route

If the capability is disabled, users need a supported manual path for unfinished work. Show which operations completed and which remain pending so staff do not repeat successful changes.

Reconcile uncertain operations before retiring the rollout infrastructure. Keep operation records long enough for the documented retry and support windows. Once the first mutation is dependable, add further capabilities individually, reviewing their combined authority rather than assuming the first rollout proves all future write tools safe.

Primary sources

OWASP: authorisation guidanceAWS Builders' Library: idempotent APIs

References checked 11 September 2026.