Idempotência

As tools de criação e alteração aceitam um argumento idempotency_key. Ele é enviado ao endpoint como o cabeçalho X-Idempotency-Key que a API REST já honra — veja Idempotência na API.

{ "name": "finance_payables_create",
  "arguments": {
    "company_id": "…",
    "description": "Aluguel de novembro",
    "amount": 4500,
    "due_date": "2026-11-10T00:00:00Z",
    "person": { "name": "Imobiliária Centro" },
    "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11"
  } }

Formato	String opaca, 1 a 255 caracteres. Um UUID é a escolha usual.
Repetição com o mesmo corpo	Devolve a resposta original, sem rodar a operação de novo.
Repetição com corpo diferente	Conflito (IDEMPOTENCY_KEY_REUSED).

Tools que apagam não aceitam o argumento: a rota não o lê, e apagar duas vezes já dá o mesmo resultado.

Por que um agente precisa disto mais que o seu backend

Um cliente MCP que dá timeout e tenta de novo, ou um modelo que decide "não tenho certeza se aquilo funcionou, vou refazer", é exatamente o padrão que cria o segundo título e o segundo lançamento. Seu backend tem um laço de retry que você escreveu; o agente tem um julgamento.

Mande uma chave sempre que a operação criar algo. Uma chave nova é uma tentativa nova; para repetir com segurança, repita a mesma.

As que movem dinheiro: a chave é obrigatória

Nestas quatro a chave não é opcional — a tool recusa a chamada sem ela, como a rota:

Tool	O que faz
finance_payables_send_to_bank	Manda o pagamento ao banco pela Kobana
finance_payables_cancel_dispatch	Cancela o envio ao banco
finance_receivables_charge	Emite boleto ou Pix para o cliente
finance_receivables_charge_cancel	Cancela a cobrança

Um envio duplicado é um pagamento duplicado, e uma cobrança duplicada é uma dívida duplicada — nenhum _delete desfaz isso. São também tools destructive: o servidor só as roda depois de confirmar com a pessoa — veja Confirmação de tools destrutivas.