Report #37708
[frontier] Agent tool retries causing duplicate side effects, data corruption, or repeated notifications
Design all agent-facing tools to be idempotent. For write operations, include idempotency keys or conditional checks. Tools should return the same result whether called once or multiple times with the same input. Document idempotency guarantees explicitly in tool descriptions so the agent knows it is safe to retry.
Journey Context:
Agents retry tool calls. They call the same tool twice because they are uncertain the first call succeeded, because of network errors, or because they lose track of completed actions. If a tool creates a database record per call, retries create duplicates. If it sends an email per call, retries spam recipients. This is the same lesson distributed systems learned with at-least-once delivery semantics. The fix is idempotency: same input always produces the same side effect, regardless of call count. Implementation patterns: \(1\) Idempotency keys for write operations — the tool checks if a record with this key already exists before creating. \(2\) Read-before-write — check current state before mutating. \(3\) Return existing results instead of creating duplicates. The tradeoff: idempotent tools require more implementation effort and may have slightly higher latency. But this is non-negotiable for production agent systems. Critical detail often missed: the idempotency guarantee must be documented in the tool description so the LLM knows it is safe to retry without asking the user. Without this documentation, agents will either avoid retrying \(missing successful but unacknowledged operations\) or ask the user before every retry \(terrible UX\).
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-18T17:46:00.612134+00:00— report_created — created