Mover Instrução para a Ferramenta

Problema

As regras de quando e como usar cada ferramenta estão no system prompt, longe da definição da ferramenta, e o modelo escolhe errado. É um dos sintomas de Ferramentas Demais.

Imagine o bot de suporte de uma operadora de internet. O system prompt tem 120 linhas, e a linha 40 diz: “use find_customer SOMENTE com CPF ou email”. Mesmo assim, o trace mostra find_customer(query="Maria Silva") voltando 300 clientes, e o modelo escolhendo o primeiro da lista. A regra existe. Ela só está no lugar errado.

Solução

Mova cada regra de uso para a descrição da ferramenta a que ela se refere: quando usar, quando não usar, o que cada parâmetro significa e o que volta. O system prompt fica com o comportamento geral.

Antes e depois

 SYSTEM = """Você é o assistente de suporte.
-Para buscar clientes, use find_customer SOMENTE com CPF ou email, nunca com nome.
-Antes de cancel_order, SEMPRE confirme o motivo com o cliente.
-Use get_invoice apenas para faturas dos últimos 12 meses; para mais antigas,
-oriente o cliente a usar o portal.
-NUNCA chame refund sem antes chamar get_order para ver o status."""
+SYSTEM = "Você é o assistente de suporte. Seja direto e confirme ações antes de executá-las."

 TOOLS = [
-  tool("find_customer", "Busca cliente.", {"query": str}),
+  tool("find_customer",
+       "Encontra um cliente por CPF ou email (nunca por nome, que é ambíguo). "
+       "Use antes de qualquer consulta de pedido ou fatura.",
+       {"by": "cpf" | "email", "value": str}),
-  tool("get_invoice", "Busca fatura.", {"id": str}),
+  tool("get_invoice",
+       "Devolve uma fatura dos últimos 12 meses. Para faturas mais antigas, "
+       "devolve erro com o link do portal, que deve ser repassado ao cliente.",
+       {"invoice_id": str}),
-  tool("refund", "Reembolsa.", {"order_id": str}),
+  tool("refund",
+       "Reembolsa um pedido entregue. Exige que get_order tenha sido chamado na "
+       "mesma conversa; o sistema recusa reembolsos sem essa consulta.",
+       {"order_id": str, "reason": str}),
 ]

Antes: as regras ficam no prompt, longe das ferramentas.

flowchart LR
  S[("1. System prompt com regras de ferramentas")]:::store --> M(["2. Modelo escolhe"]):::llm
  T["Ferramentas com descrições vagas"]:::tool --> M
  M --> X(["3. Escolha errada às vezes"]):::io

Depois: cada regra mora na ferramenta, e as regras críticas também no código.

flowchart LR
  S[("1. System prompt curto")]:::store --> M(["2. Modelo escolhe"]):::llm
  T["Ferramentas com descrição completa"]:::tool --> M
  M --> V["3. Ferramenta valida as próprias regras"]:::tool
  V --> OUT(["4. Escolha certa ou erro explicativo"]):::io

1. O system prompt fica com o comportamento geral.
2. O modelo lê nome, descrição e parâmetros como uma unidade quando monta a chamada.
3. A ferramenta reforça em código as regras que não podem falhar.
4. Se o modelo erra, recebe um erro que explica o motivo e o que fazer.

Por que funciona

O modelo decide qual ferramenta chamar, e com quais argumentos, olhando a definição de cada uma. Nome, descrição e schema chegam juntos. Uma regra na descrição é lida exatamente quando o modelo pensa em find_customer. A mesma regra solta no system prompt, entre outras cem frases, compete com tudo ao redor.

Descrições completas também tornam as ferramentas portáteis. Se a mesma ferramenta for usada por outro agente ou exposta por MCP, as regras vão junto. Uma regra presa no prompt de um agente some quando a ferramenta muda de casa.

E regras que não podem falhar ganham uma segunda camada: a ferramenta recusa a chamada indevida e devolve um erro útil. O prompt orienta; o código garante.

Quem constrói agentes chegou à mesma conclusão. No post “Building effective agents” (dez. 2024), a Anthropic conta que, no agente que montou para o benchmark SWE-bench, gastou mais tempo ajustando as ferramentas do que o prompt geral. Um exemplo: o modelo errava com caminhos de arquivo relativos, então a ferramenta passou a exigir caminhos absolutos. O post chama isso de poka-yoke, o termo japonês para um desenho que torna o erro difícil de cometer.

Anatomia de uma boa descrição

Uma descrição útil responde a cinco perguntas, em poucas frases:

• O que faz. “Encontra um cliente por CPF ou email.”
• Quando usar. “Antes de qualquer consulta de pedido ou fatura.”
• Quando não usar. “Nunca por nome, que é ambíguo.”
• O que cada parâmetro significa. De preferência no schema, com enum e formato.
• O que volta, inclusive no erro. “Para faturas antigas, devolve o link do portal.”

Passo a passo seguro

0. Meça. Rode o eval e conte as escolhas erradas de ferramenta e as chamadas com argumentos inválidos. Guarde alguns traces de erro como exemplo.
1. Encontre no prompt as regras sobre ferramentas. Toda frase que cita o nome de uma ferramenta é candidata.
2. Reescreva a descrição de cada ferramenta com: o que faz, quando usar, quando não usar, o significado de cada parâmetro e o que volta.
3. Use o schema para o que dá: enums, formatos, campos obrigatórios. Um by com enum cpf ou email não deixa espaço para “nome”.
4. Reforce em código as regras críticas e devolva erros que ensinam o modelo a corrigir.
5. Remova as regras do prompt.
6. Meça de novo. Menos escolhas erradas e menos argumentos inválidos.

Um erro que ensina

O passo 4 é onde a refatoração deixa de ser só texto. Quando o modelo chama refund sem ter consultado o pedido, a ferramenta não executa e devolve:

{
  "error": "order_not_checked",
  "message": "Chame get_order com este order_id antes de reembolsar. O reembolso só vale para pedidos com status 'entregue'.",
  "retryable": true
}

Compare com um 500 Internal Server Error. O erro genérico deixa o modelo tentando de novo do mesmo jeito. O erro explicativo diz o próximo passo, e na volta seguinte o modelo chama get_order.

Riscos

• Descrições longas demais. Muitas ferramentas com descrições enormes somam tokens. Seja específico e curto.
• Regras gerais que se perdem. Uma regra que vale para várias ferramentas (“confirme antes de qualquer ação com efeito”) pode ficar no system prompt.
• Descrição que contradiz o código. Se a descrição diz uma coisa e a validação faz outra, o modelo se confunde. Mantenha os dois juntos no código, de preferência no mesmo arquivo.

Erro comum: a descrição promete o que o código não faz

A descrição de refund diz “o sistema recusa reembolsos sem essa consulta”. Se ninguém escreveu essa checagem, a frase é só uma ameaça vazia. Na maioria das conversas o modelo obedece. Na conversa em que o cliente insiste (“já falei o número, só reembolsa”), ele pula a consulta e o reembolso passa.

Regra que envolve dinheiro, dado pessoal ou ação irreversível precisa existir nas duas camadas. A descrição reduz as tentativas erradas; o código bloqueia as que sobram.

Desafio

Reescreva a descrição desta ferramenta a partir das regras que estavam no prompt.

Ferramenta: schedule_visit(date, address)  "Agenda visita técnica."
Regras no prompt: visitas só em dias úteis; só para endereços com CEP da
cidade de São Paulo; o cliente precisa ter um chamado aberto; datas no formato AAAA-MM-DD.

schedule_visit(ticket_id, date, cep)
  Agenda uma visita técnica para um chamado aberto. Só atende CEPs da cidade
  de São Paulo (faixas 01000-000 a 05999-999 e 08000-000 a 08499-999) e dias
  úteis. Se a data cair em fim de semana ou feriado, devolve erro com as
  próximas três datas disponíveis.
  ticket_id: número do chamado aberto do cliente.
  date: data no formato AAAA-MM-DD.
  cep: só dígitos.

Teste seu entendimento