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.