Order management + returns as tools

Context

An order management system is exposed to a service agent. Reads are open; the one mutation, cancel_order, requires an idempotency key and is rate limited, so a retrying or looping agent can't issue two refunds for one order.

The decision

Which mutations need idempotency keys and human confirmation: any money moving or irreversible action gets an idempotency key so retries are safe.

What most miss

Everyone tests the happy path. The failure that matters is the agent that retries on a timeout, without idempotency that's a double refund, and it's the server's job to prevent it.

Stakes

A double refund bug at scale is direct margin loss and a reconciliation nightmare.