Resources e prompts

Além das tools, o servidor oferece três coisas que o cliente usa por conta própria: resources (documentos que o usuário anexa à conversa), prompts (roteiros prontos que o usuário escolhe) e completions (autocomplete dos argumentos dos dois). Na era 2026-07-28, ele também pede confirmação antes de rodar uma tool destrutiva.

Nada disso abre um caminho novo até os seus dados: tudo passa pelas mesmas tools, sob as mesmas permissões e o mesmo escopo do token. Resources, prompts e completions só leem, então continuam disponíveis com um token só de leitura.

Resources

Um resource é um documento identificado por uma URI. O usuário escolhe, por exemplo, uma cobrança, e o cliente lê o documento e o põe no contexto, sem que o modelo precise chamar uma tool.

URI	Lido por	O que volta
kobana://dunning/me	dunning_me	A identidade da conexão: pessoa, organização, escopos, expiração do token (JSON)
kobana://dunning/metrics/recovery	dunning_metrics_recovery	As métricas de recuperação (JSON)
kobana://dunning/notification-preferences	dunning_notification_preferences_get	As preferências de notificação (JSON)
kobana://dunning/people/{id}	dunning_people_get	Um devedor (JSON)
kobana://dunning/people/{id}/statement-pdf	dunning_people_statement_pdf	O extrato do devedor (PDF)
kobana://dunning/charges/{id}	dunning_charges_get	Uma cobrança (JSON)
kobana://dunning/charges/{id}/settlement-pdf	dunning_charges_settlement_pdf	A carta de quitação (PDF; só de cobrança paga)
kobana://dunning/agreements/{id}	dunning_agreements_get	Um acordo (JSON)
kobana://dunning/agreements/{id}/pdf	dunning_agreements_pdf	O termo de acordo (PDF)
kobana://dunning/disputes/{id}	dunning_disputes_get	Uma disputa (JSON)
kobana://dunning/collection-rules/{id}	dunning_collection_rules_get	Uma régua de cobrança (JSON)
kobana://dunning/collection-rules/{id}/steps	dunning_collection_rule_steps_list	Os passos de uma régua (JSON)
kobana://dunning/templates/{id}	dunning_templates_get	Um modelo de mensagem (JSON)

resources/list traz as URIs fixas e resources/templates/list os templates com {id}.

• Permissões. Cada resource é lido pela tool da coluna do meio. Ele só aparece, e só é lido, se você pode rodar essa tool.
• Binários. PDFs voltam em base64 (blob), até 10 MB. Diferente das tools, que só descrevem o arquivo, aqui o documento é a resposta: foi o cliente que pediu por ele.
• Não encontrado. URI desconhecida, ou registro que não existe nesta organização, é -32002 na era 2025 e -32602 na 2026-07-28 — veja Erros.
• Sem assinatura de mudanças. O servidor é stateless: não há resources/subscribe nem aviso de lista alterada.

Prompts

Um prompt é uma instrução pronta que você escolhe no cliente e que vira a primeira mensagem da conversa. Ele só aparece se você pode rodar todas as tools em que se apoia.

Todos os prompts só leem. Nenhum envia mensagem, negativa ou protesta: cada um termina sugerindo os próximos passos e dizendo ao modelo para não agir sem que você peça.

Prompt	Argumentos	O que faz
review_overdue_charges	person_id (opcional, UUID)	Reúne as cobranças vencidas — overdue, ou pending com vencimento até ontem, com a data já calculada —, mostra uma tabela por antiguidade, agrupa por faixa de atraso (até 30, de 31 a 90 e mais de 90 dias) e sugere os próximos passos.
debtor_overview	person_id (obrigatório, UUID)	O retrato de um devedor: dados, cobranças, acordos e as últimas interações.
recovery_report	months (opcional, de 1 a 24, padrão 6)	Relatório de recuperação: valor e quantidade recuperados, taxa, dias médios de atraso, passos médios da régua, o que segue vencido, a série mensal e as quebras por método e canal.
pending_legal_actions	—	As negativações e os protestos com status pending — aguardando aprovação humana —, apontando inconsistências. Não aprova nem cancela nada.

Argumento obrigatório ausente, ou fora do formato, é -32602.

Completions

completion/complete sugere valores enquanto você digita um argumento:

• person_id e o {id} de devedores, cobranças e modelos de mensagem: busca na listagem correspondente com search, sob a mesma permissão dela. Se você não pode listar, não há sugestão.
• O {id} de acordos, disputas e réguas de cobrança: os ids mais recentes da listagem, filtrados pelo prefixo digitado.
• months: 3, 6, 12 e 24.

No máximo 100 valores por resposta. Sem fonte de sugestão, a resposta é uma lista vazia — nunca um erro —, e você continua digitando.

Confirmação de tools destrutivas

Tools destrutivas são marcadas com destructiveHint:

• as que apagam ou arquivam, inclusive em lote;
• as que cancelam: cobranças em lote, acordos, protestos, negativações;
• as que falam com o devedor ou com terceiro: notificar uma cobrança (dunning_charges_notify), criar ou reenviar uma notificação (dunning_notifications_create, dunning_notifications_resend), negativar (dunning_negativations_create), protestar (dunning_protests_create), aprovar uma negativação ou um protesto, testar e reenviar webhook;
• as que decidem sobre a dívida: aplicar uma régua a cobranças (dunning_charges_bulk_assign_rule, que dispara mensagens), aceitar um acordo (dunning_agreements_accept), resolver uma disputa (dunning_disputes_update), criar ou encerrar uma campanha de desconto;
• e a que rotaciona o segredo de um webhook.

Uma atualização comum de configuração não é destrutiva.

O servidor não confia só no cliente: na era 2026-07-28, com um cliente que declara suporte a formulários de elicitation, ele mesmo pede a confirmação:

1. O primeiro tools/call não roda nada. Ele volta resultType: "input_required" com um formulário de uma pergunta (elicitation/create, um booleano "Run this action") e um requestState.
2. O cliente mostra a pergunta e reenvia a mesma chamada com o requestState e a resposta em inputResponses.confirm.
3. Só um sim explícito executa — action: "accept" com confirm: true. Recusar ou cancelar volta um resultado isError com USER_DECLINED, e nada muda.

A confirmação vale só para aquela chamada: a mesma tool, os mesmos argumentos, a mesma pessoa e organização, por 5 minutos. Uma resposta não pode ser reaproveitada para outra cobrança ou outra ação; se o estado faltar, tiver vencido ou não bater, o servidor simplesmente pergunta de novo. E ela é de uso único: reenviar uma chamada já confirmada volta isError com confirmation_replayed, sem executar nada — para repetir a ação, chame a tool de novo e confirme outra vez.

Um cliente que não consegue confirmar — na era 2025, ou na 2026-07-28 sem declarar formulários de elicitation — não roda tools destrutivas: a chamada volta isError com confirmation_required e nada é executado. Leituras e escritas comuns seguem funcionando. Se o servidor não consegue registrar a confirmação naquele momento, a tool também é recusada, com confirmation_unavailable; tente de novo depois.