Idempotency and concurrency
Retry keys
Every write accepts an optional idempotency_key of 8–128 characters. Generate a unique key for each intended action. The server keeps a replay receipt for 24 hours, scoped to the account and client. The same key with the same input returns the original result. A different input or operation with that key returns idempotency_key_reused.
A retry receipt can contain the original result, including user text. It is private persistence, separate from the metadata-only activity log. Expiry makes a receipt ineligible; physical deletion depends on the purge job.
After a timeout, keep both the key and arguments unchanged. After the replay window expires, reread before attempting a new action. create_behavior without a key is not idempotent and can create duplicates.
Check before changing
set_occurrence_status accepts expected_status. update_behavior requires expected_revision. Other existing-record writes accept expected_revision as an optional guard. Read the latest record and pass its opaque revision without interpreting it.
A stale guard returns conflict and changes nothing. Do not retry by stripping the guard. Reread, compare the user’s intended edit, and obtain any confirmation the revised action needs.
Safe edit sequence
- Read the target by ID and show the user the intended change.
- Obtain explicit direction and any host confirmation.
- Send the change, concurrency guard and a new retry key.
- Inspect isError and the result. If delivery is uncertain, retry the identical request with its original key.
- Treat changed=false as a valid no-op when returned; do not manufacture another edit.
The tool examples describe the exact fields for each operation. Annotation idempotentHint describes ordinary tool semantics; it does not replace receipt-backed create retries.