🔧 Ferramentas e o Contrato de Ferramenta
Listar as ferramentas não basta. Sua IA vai chamar a ferramenta errada, ignorar dependências, ou fazer dez chamadas em fila onde uma em lote resolvia. A cura é o Contrato de Ferramenta: para cada ferramenta, dizer quando chamar, o que vem antes, o que nunca usar, e como agrupar. Você sai daqui com seis cláusulas prontas pra colar.
Conteúdo detalhado
Gatilho de uso: quando chamar
No módulo da biblioteca você viu o bloco ferramentas dizer o que existe. Isso é só metade. A outra metade — a que faz a IA parar de tatear — é o gatilho de uso: a condição clara que diz quando aquela ferramenta entra. "Você tem uma busca na web" é uma capacidade. "Use a busca quando precisar de um fato posterior ao seu corte de conhecimento" é um contrato. A diferença é noite e dia.
🎯 A ideia em uma frase
O Contrato de Ferramenta diz quando e em que ordem chamar cada ferramenta — não só o que existe. Listar é a Declaração de Capacidades; contratar é o passo seguinte, e é o que separa um agente que executa com disciplina de um que chama a coisa errada na hora errada.
O coração de cada cláusula é o gatilho: "use quando {condição}". Sem ele, o modelo adivinha — e adivinha mal: chama a busca pra coisas que já sabe, ou deixa de chamar quando precisava de verdade.
O que é o gatilho
Uma frase que amarra a ferramenta a uma situação observável: "use a calculadora quando a conta tiver mais de um passo", "use a busca quando o usuário pedir algo atual", "use o leitor de arquivo quando precisar do conteúdo, não do nome". O gatilho responde à única pergunta que importa no momento de agir: isto se aplica agora?
Por que o gatilho muda tudo
Porque sem condição de disparo, a ferramenta vira tentação. O modelo ou abusa (chama pra tudo, gasta tempo e tokens) ou ignora (responde de cabeça quando devia ter buscado). O gatilho transforma "você pode" em "você deve, exatamente aqui" — e é a parte do contrato que mais reduz chamada errada.
Pré-requisito: o passo obrigatório antes
Algumas ferramentas têm uma ordem sagrada: antes de fazer X, faça Y. O exemplo clássico, que aparece literalmente nas regras de ferramentas reais, é ler antes de editar: você não pode editar um arquivo que nunca leu — porque se não viu o conteúdo atual, a edição é um chute. O pré-requisito é a cláusula que torna essa dependência explícita.
You MUST use the Read tool at least once before editing.
Uma frase. Maiúsculas no MUST, a ordem explícita ("at least once before editing"). Não é sugestão — é a porta que precisa ser aberta antes da próxima.
🔗 Por que declarar a ordem importa
- ① A IA não infere a dependência sozinha. Pra ela, editar e ler são duas ferramentas separadas. Você precisa amarrar uma à outra.
- ② Pular o passo gera dano silencioso. Editar sem ler sobrescreve o que você não viu — e o erro só aparece depois, quando já é tarde.
- ③ A regra é curta e custa pouco. Uma linha no contrato evita uma classe inteira de falhas. ROI altíssimo.
O molde do pré-requisito
Pré-requisito: antes de {ação}, {passo obrigatório}. Exemplos: "antes de editar, leia o arquivo"; "antes de enviar o e-mail, mostre o rascunho"; "antes de rodar o deploy, rode os testes". Sempre antes de + a porta que precisa estar aberta.
Exclusão: use X, nunca Y
Quando duas ferramentas parecem servir pro mesmo caso, a IA escolhe — e às vezes escolhe a pior. A cláusula de exclusão tira a escolha das mãos dela: "para este caso, use X, nunca Y". O exemplo que define o padrão vem do Cursor: use a ferramenta dedicada de arquivo, nunca o terminal.
Use specialized tools instead of terminal commands when possible… don't use cat/head/tail to read files, don't use sed/awk to edit files… Reserve terminal commands exclusively for actual system commands.
Repare na forma: diz o que usar (a ferramenta dedicada), o que não usar (cat, head, tail, sed, awk) e reserva o terminal pro que de fato é comando de sistema. Escolha eliminada.
✓ Exclusão que funciona
- ✓"Para ler arquivo, use o leitor — nunca o terminal"
- ✓Nomeia a vencedora E a proibida, sem ambiguidade
- ✓Vale só pro caso ("para isto"), não pra tudo
- ✓Resolve uma confusão real que você já viu acontecer
✗ Exclusão que atrapalha
- ✗"Não use o terminal" — sem dizer o que usar no lugar
- ✗Proíbe sem caso ("nunca, jamais"), travando usos legítimos
- ✗Cria exclusão entre ferramentas que não se sobrepõem
- ✗Inventa uma regra pra um conflito que nunca ocorreu
<ferramentas> Para ler/editar arquivos, use a ferramenta dedicada — nunca o terminal. Reserve o terminal só para comandos de sistema de verdade (git, mkdir, mover). </ferramentas>
Batching e paralelismo
Aqui mora um ganho enorme de velocidade que quase ninguém escreve no prompt: quando você precisa de várias coisas que não dependem uma da outra, peça todas de uma vez, no mesmo bloco — em paralelo. Ler três arquivos diferentes? Buscar duas coisas distintas? Não há motivo pra fazer em fila. A regra de paralelismo do Claude Code diz isso de forma direta.
If you intend to call multiple tools and there are no dependencies between the calls, make all of the independent calls in the same block.
A condição é "no dependencies between the calls"; a ação é "make all of the independent calls in the same block". Independente → junto. Dependente → não (isso é o próximo tópico).
Sem contrato: em fila, sem motivo
A IA lê o arquivo A, espera, lê o B, espera, lê o C. Três idas e voltas.
Nada ali dependia de nada — A, B e C são independentes. Mas sem a regra, o modelo serializa por hábito. O usuário espera o triplo do necessário, e a tarefa fica lenta à toa.
Com contrato: todas no mesmo bloco
A IA dispara as três leituras juntas e lê as três respostas que voltam.
Uma ida só. O contrato de batching diz: chamadas independentes → no mesmo bloco, em paralelo. O resultado é o mesmo, mas chega numa fração do tempo. Velocidade de graça.
O teste da independência
Antes de agrupar, pergunte: "a chamada B precisa do resultado da A?" Se a resposta é não pra todas, vão todas juntas. Se alguma precisa, essa fica de fora do bloco e espera. Batching só vale pro que é genuinamente independente — não force paralelo onde há dependência.
Não citar o nome da ferramenta ao usuário
Uma cláusula pequena de etiqueta, com efeito grande na experiência: ao falar com o usuário, descreva a ação em linguagem natural — não recite o nome interno da ferramenta. O usuário quer saber "estou procurando isso pra você", não "vou invocar a função web_search com o parâmetro query". O nome da ferramenta é assunto de bastidor.
✓ Diga assim (linguagem natural)
- ✓"Deixa eu procurar isso pra você…"
- ✓"Vou ler o arquivo pra ver o que tem lá"
- ✓"Calculei e o total é R$ 1.240"
- ✓Descreve a intenção, não o mecanismo
✗ Não diga assim (vaza o bastidor)
- ✗"Chamando a tool search_web…"
- ✗"Executando read_file(path=…)"
- ✗"Vou usar a função calculator agora"
- ✗Expõe nomes internos que não dizem nada ao usuário
Não cite o nome da ferramenta ao falar com o usuário; diga em linguagem natural o que está fazendo.
Por que isso importa de verdade
O nome da ferramenta é detalhe de implementação. Citá-lo polui a conversa, confunde quem não é técnico e amarra o seu prompt a nomes que podem mudar. A regra mantém a IA falando de resultados, não de encanamento — e a experiência fica limpa.
Encadeamento: usar o resultado anterior
O oposto do batching: às vezes a chamada B só faz sentido com o que a A devolveu. Aí não dá pra paralelizar — tem que ser em série, e a B precisa consumir o output exato da A. Esse é o encadeamento: o contrato que diz "pegue tal campo do resultado anterior e passe pra próxima". Sem ele, a IA inventa o elo — e quebra o pipeline.
A — buscar: "encontre o ID do pedido pelo e-mail do cliente"
devolve: pedido_id = 8842
B — detalhar: "abra os detalhes do pedido {pedido_id}"
contrato: use exatamente o pedido_id que A devolveu — não chute um número.
Repare no padrão: a cláusula de encadeamento nomeia qual campo sai de A e para onde entra em B. Quanto mais exato o formato declarado ("o pedido_id no formato numérico"), menos a IA improvisa. É o irmão da exclusão: um diz qual ferramenta, o outro diz com qual dado.
⚠️ Os três erros de encadeamento
Quando o pipeline quebra, quase sempre é um destes:
- 1.Paralelizar o que é dependente. B sai junto de A e usa um valor que ainda não existe → erro ou lixo.
- 2.Inventar o elo. A IA não pega o campo real de A; chuta um valor plausível e segue → resultado errado, sem aviso.
- 3.Formato impreciso. O contrato não diz qual campo nem em que formato → a IA pega o pedaço errado do output.
🛠️ Mão na massa: seu entregável
Pegue uma IA sua que use ferramentas e escreva o contrato delas. Em 15 minutos você fecha as seis cláusulas.
- 1 Liste as ferramentas que a sua IA realmente tem. Para cada uma, escreva o gatilho: "use quando {condição}".
- 2 Marque os pré-requisitos (alguma precisa de um passo antes? ex.: ler antes de editar) e as exclusões (duas se confundem? "use X, nunca Y").
- 3 Escreva a regra de batching ("independentes → no mesmo bloco") e marque os encadeamentos (B precisa de qual campo de A?).
- 4 Adicione a linha de etiqueta ("não cite o nome da ferramenta ao usuário"). Cole tudo no bloco <ferramentas>, rode uma tarefa real e veja se a IA escolhe e agrupa certo.
📝 Resumo do Módulo
- ✓O Contrato de Ferramenta diz quando e em que ordem chamar — não só o que existe
- ✓Gatilho: amarre a ferramenta a uma condição observável — "use quando {condição}"
- ✓Pré-requisito: o passo obrigatório antes — ex.: ler antes de editar
- ✓Exclusão: "use X, nunca Y" para o caso — escolha errada eliminada
- ✓Batching: chamadas independentes → no mesmo bloco, em paralelo; dependentes → encadeadas em série
- ✓Etiqueta: ao usuário, diga a ação em linguagem natural — não cite o nome da ferramenta
➡️ Próximo Módulo
2.5 — 🔁 O Loop operacional. Você contratou as ferramentas; agora vamos dar à IA o ciclo de trabalho que usa esses contratos com disciplina: aterrar, raciocinar, agir, observar, verificar, narrar — o cérebro do agente.