Repetição e operações assíncronas
As tools não aceitam chave de idempotência. Uma chamada que cria um registro e é repetida cria outro: o segundo boleto, a segunda cobrança Pix, a segunda transferência. Um cliente MCP que dá timeout e tenta de novo, ou um modelo que decide "não tenho certeza se funcionou, vou refazer", é exatamente o padrão que produz a duplicata.
O que protege contra a segunda execução
- A confirmação de uso único. Na era
2026-07-28, com um cliente que suporta formulário de elicitation, toda tool destrutiva só roda depois de você confirmar, e cada confirmação roda a chamada uma vez. Reenviar a chamada já confirmada não a executa de novo: você é perguntado outra vez, com o aviso de que a aprovação anterior já foi usada. Veja Confirmação de tools destrutivas. - A leitura antes da repetição. Antes de repetir uma criação que pode ter funcionado, procure o registro. Quando a tool de criação aceita
external_id, mande um identificador seu e, antes de repetir, consulte a listagem filtrando por ele, onde a listagem oferece esse filtro.
As instruções do servidor pedem ao modelo que leia o boleto de volta depois de uma ação e que confirme com você antes de emitir, cancelar, protestar ou excluir boletos.
Muita coisa é assíncrona
Emitir, cancelar, alterar e protestar um boleto, registrar uma cobrança Pix ou enviar um pagamento viram comandos enviados à instituição financeira. A tool responde quando o pedido foi registrado na Kobana, não quando o banco aceitou:
| Ação | Resposta da tool | Estado final |
|---|---|---|
| Emitir boleto | O boleto em generating | opened quando o registro é confirmado, ou generation_failed |
| Cancelar boleto | O pedido de baixa registrado | canceled quando o banco confirma |
| Emitir cobrança Pix | A cobrança criada | O registration_status acompanha o registro no provedor Pix |
Para saber o estado real, leia o registro de novo com a tool *_get. Repetir a ação porque o estado ainda não mudou só cria um segundo pedido.
Falha de negócio não é motivo para repetir
"Bank billet (status paid) cannot be canceled in this status" volta como resultado com isError e o código unprocessable. O estado do registro não deixa a operação acontecer, e repetir a chamada idêntica dá a mesma recusa. O modelo deve explicar o motivo, não tentar de novo. Veja Erros.