Retrying is a fact. Charging twice isn't.

In an agent, tools get retried. A lot. Reasons:

• Network timeouts (the first call vanished in the wire).
• The agent changes its mind mid-turn and re-invokes.
• A generic retry handler you didn't even write is also running.
• The model, seeing an ambiguous error, tries again.

If the tool has side effects (creates a record, charges money, sends a mail), retrying without protection means: two records, double charge, two mails. For the user, that's a production bug that costs trust and money.

The solution is idempotency: design the tool so that calling it N times with the same parameters is equivalent to calling it once.

Three ways to make a tool idempotent

1. Naturally idempotent. Some operations already are. set_status("active") called 5 times leaves the same state. No extra work needed.

2. By idempotency_key. The client (or the agent) generates a unique key per intent and passes it. The server remembers that key and the result. If the key repeats, it returns the previous result without re-executing. This is the canonical pattern for creating things (payments, orders, records).

3. By state check. Before acting, the handler checks if the effect already happened. assign_shift can check whether the crewmate is already on that shift and, if so, return { ok: true, already_assigned: true }.

The idempotency_key contract

When you support idempotency_key:

• Document it in the tool description. The agent learns it and starts generating keys with req-{uuid} or similar.
• Mark it optional (not required). Some clients won't pass it; that's valid but means "no protection".
• Return a replayed flag or equivalent. The agent needs to know whether the operation created something new or returned an existing result.
• Store the key → result association persistently. If you only keep it in memory, a retry after restart loses the protection.

Pattern in code

async function handle({ ..., idempotency_key }) {
  if (idempotency_key) {
    const prev = await db.payments.findByIdempotencyKey(idempotency_key);
    if (prev) {
      return { ok: true, payment_id: prev.payment_id, replayed: true };
    }
  }
  const payment = await db.payments.create({ ..., idempotency_key });
  return { ok: true, payment_id: payment.payment_id, replayed: false };
}

Your task

On the right you have register_payment. The starter charges every time it's called. Make it idempotent.

In agents that touch money, external state, or humans, idempotency is not optional. It's the difference between a system you can operate and a system you support every week because "it duplicated".