Make tools that change things safe to repeat

How to do it

Models and retry logic both repeat calls. A model that repeats itself sends a new tool call ID, so the ID alone is not enough. Derive the key from the conversation and the thing the call acts on, such as the order line. Store the key with the result and return the stored result on a repeat. The idempotency keys rule shows the server side. Tools that pay, send or delete also need a person's approval.

Example

async function createReturn(args: ReturnArgs, ctx: ToolContext) {
  const key = `${ctx.conversationId}:${args.orderNumber}:${args.lineId}`;
  return idempotent(key, () => returns.create({ ...args, customerId: ctx.user.id }));
}

def create_return(args: ReturnArgs, ctx: ToolContext) -> dict:
    key = f"{ctx.conversation_id}:{args.order_number}:{args.line_id}"
    return idempotent(key, lambda: returns.create(**args.model_dump(), customer_id=ctx.user.id))

How to check

A test calls create_return twice for the same order line, with two different tool call IDs. One return exists, and both calls get the same result.