Melhores Práticas de Tool Calling em Agentes: Por Que Seu Agente Escolhe a Ferramenta Errada

Melhores Práticas de Tool Calling em Agentes: Por Que Seu Agente Escolhe a Ferramenta Errada

As melhores práticas de tool calling em agentes são o que separa um demo funcional de um agente que chama a ferramenta errada silenciosamente em produção. A equipe de engenharia da Anthropic mediu que uma única descrição reescrita cortou um resultado de ferramenta de 206 tokens para 72, e o Claude Code agora limita cada resposta de ferramenta a 25.000 tokens porque o desperdício é real. Seu agente falha de quatro formas: ferramenta errada, argumentos errados, loops descontrolados e sangria de tokens. E cada uma tem uma correção que você pode implementar esta semana.

Principais conclusões:

• Tool calling em agentes falha de exatamente quatro formas: ferramenta errada, argumentos errados, loops descontrolados e sangria de tokens.
• Descrições de ferramentas são a única instrução que o modelo vê no momento da seleção, então elas corrigem a maioria das chamadas erradas.
• Schemas planos, moldados à tarefa, com entradas validadas eliminam a maioria das falhas de argumentos errados.
• Respostas concisas de ferramentas e um loop de avaliação a cada mudança mantêm custo de tokens e regressões mensuráveis.

Por que o tool calling em agentes falha em produção?

O tool calling em agentes falha de quatro formas: o modelo escolhe a ferramenta errada, escreve argumentos errados, entra em um loop descontrolado ou sangra tokens através de respostas gordas. Cada falha atinge uma etapa diferente do loop de chamada, então a ordem de correção importa. Comece pela seleção, porque uma escolha errada de ferramenta envenena cada etapa depois dela.

A prescrição completa de relance:

Trabalhe nessa ordem. As práticas 1 e 2 levam uma tarde e removem a maioria das falhas de ferramenta errada e argumentos errados que você vê hoje. Uma descrição de ferramenta não é documentação. É a única instrução que o modelo recebe no momento da seleção.

Fase 1: Projete ferramentas que o modelo realmente consiga usar

Os ganhos de confiabilidade mais baratos em tool calling de agentes estão nas suas definições de ferramentas, não nos seus prompts ou na escolha do modelo. O modelo nunca lê sua documentação de API ou seu README. Ele vê um nome, uma string de descrição e um schema JSON, e decide apenas com isso. Acerte esses três e a precisão de seleção melhora antes de você tocar em qualquer outra coisa.

Prática 1: Escreva descrições que o modelo consiga usar

Escreva descrições de ferramentas como instruções para o modelo, não como documentação de API. Uma descrição que satisfaz um desenvolvedor humano ("wrapper REST para o endpoint de usuários") não dá ao modelo nada para decidir. O guia de engenharia da Anthropic sobre escrita de ferramentas e suas melhores práticas de definição de ferramentas ambos empurram o mesmo padrão: diga quando usar a ferramenta, o que ela retorna e quando NÃO usá-la.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

versus a versão que a maioria das equipes entrega:

{
  "name": "get_user",
  "description": "Gets a user."
}

Duas regras fazem a maior parte do trabalho aqui. Primeira, nomeie parâmetros para que o significado seja inequívoco: user_id, nunca user ou id, porque user convida o modelo a passar um nome ou email onde um UUID deveria ir. Segunda, declare exclusões explicitamente. "Do NOT use to search users" previne mais chamadas erradas do que qualquer quantidade de descrição positiva, porque modelos confundem ferramentas sobrepostas com muito mais frequência do que entendem mal ferramentas únicas e claramente delimitadas. Para a mecânica em nível de provedor de como essas definições chegam às APIs da OpenAI, Anthropic e Google, veja nosso guia de function calling multi-provedor.

Prática 2: Mantenha schemas planos e moldados à tarefa

Mantenha schemas de entrada planos, com cada campo que a tarefa realmente precisa e nenhum que não precisa. Objetos aninhados com branches opcionais são onde falhas de argumentos errados se multiplicam: o modelo precisa inferir uma estrutura da qual nunca vê exemplos. O guia de function calling da OpenAI aceita JSON Schema arbitrário, mas permissivo não é o mesmo que confiável.

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Aplaine para a tarefa:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Enums vencem texto livre para qualquer campo com um conjunto limitado de valores. Arrays de required vencem tudo opcional. Se o modelo quase sempre precisa de um campo, torne-o required no schema da ferramenta mesmo quando sua API o chama de opcional. Você não está espelhando sua API. Está projetando uma superfície que um modelo específico consegue preencher corretamente.

Fase 2: Gerencie o conjunto de ferramentas, não apenas as ferramentas

A qualidade individual de ferramentas deixa de ser suficiente quando um agente carrega mais do que um punhado delas, porque erros de seleção crescem com o tamanho da lista que o modelo lê.

Prática 3: Envolva sequências multi-etapas de API em ferramentas atômicas

Colapse qualquer sequência fixa de chamadas de API em uma única ferramenta atômica. O post de engenharia da Anthropic usa schedule_event e get_customer_context como modelo: uma chamada que faz o trabalho inteiro vence três chamadas que o agente precisa encadear corretamente toda vez. Cada elo em uma cadeia é mais uma vez onde o modelo pode travar, tentar de novo erradamente ou entrar em loop.

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

A regra prática: se o modelo precisa sempre chamar B depois de A, A e B são uma ferramenta usando duas fantasias.

Prática 4: Use namespace, pode e filtre ferramentas dinamicamente

Coloque namespace em cada nome de ferramenta e mostre a cada agente apenas o subconjunto que sua tarefa atual precisa. Nomes genéricos colidem no momento em que você conecta duas integrações. Imagine um agente conectado a dois servidores MCP que ambos expõem uma ferramenta chamada search: dois verbos idênticos, sem como diferenciá-los. A Anthropic documenta ganhos mensuráveis de avaliação com namespacing por prefixo:

Podar importa tanto quanto nomear. Um agente de suporte não precisa de suas ferramentas de billing carregadas enquanto responde uma pergunta sobre senha. O padrão planner-worker, onde um planner roteia uma tarefa para um worker que carrega apenas as ferramentas relevantes, é a correção padrão; o how-to de carregamento dinâmico de ferramentas do LangGraph detalha a implementação. Quantas ferramentas são demais? Trate 5-10 por agente como uma faixa de trabalho, não uma lei: a precisão degrada conforme a lista cresce, e a cura é filtragem, não um modelo maior. Se você está escolhendo a própria camada de roteamento e filtragem, compare suas opções no nosso roundup das melhores bibliotecas de function calling.

Fase 3: Controle o que volta e o que sai

O loop roda nas duas direções, e a maioria das equipes só projeta a metade de saída. O que suas ferramentas retornam determina quanto da janela de contexto sobrevive até a próxima vez, e o que sua validação rejeita determina se o modelo aprende com seus erros ou os repete.

Prática 5: Retorne resultados concisos e de alto sinal

Retorne o menor resultado que o modelo consiga usar, com identificadores legíveis por humanos em vez de IDs brutos. O post de engenharia da Anthropic documenta uma ferramenta cujo resultado padrão rodava 206 tokens; uma configuração concisa de response_format cortou o mesmo resultado para 72 tokens, aproximadamente um terço do tamanho. Multiplique isso por dezenas de chamadas por tarefa e isso decide se seu agente termina.

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

Mais dois detalhes da mesma fonte: a Anthropic suporta um enum response_format (detailed versus concise) nas definições de ferramentas, então você pode declarar a forma que quer em vez de parsear o jato de dados. E o Claude Code limita respostas de ferramentas a 25.000 tokens, um teto rígido que trunca resultados inchados de qualquer forma. A Anthropic também relata, como sua descoberta, que resolver UUIDs para nomes semânticos reduziu mensuravelmente alucinações de recuperação, e é por isso que o payload "depois" acima diz "Dana Kim" e não c9a1...f2. Respostas gordas são um problema de custo também; veja nosso guia para reduzir custos de API LLM para o quadro completo.

Prática 6: Valide cada chamada e faça os erros ensinarem o modelo

Valide cada chamada de ferramenta no servidor e retorne erros que contenham a correção. O artigo de Martin Fowler sobre function calling enquadra sem rodeios: nunca confie na saída do modelo. Ele vai passar strings onde enums deveriam ir e inventar IDs que não existem.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

A string de erro é o jogo inteiro. Compare:

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Cada erro de validação que sua ferramenta retorna é um prompt que você está escrevendo para a próxima tentativa do modelo. Erros que nomeiam a restrição e apontam para a ferramenta corretiva transformam um loop de retry em uma recuperação de uma vez. Essa também é sua primeira linha de defesa de segurança; nosso guia de guardrails LLM cobre em profundidade.

Fase 4: Como tornar seguro e depois mensurável?

Segurança e medição são a mesma fase porque uma ação destrutiva sem gate e uma regressão não medida ambas aparecem como incidentes que você não viu chegar. Proteja as ações que não podem ser desfeitas, depois instrumente tudo para que a próxima mudança de ferramenta seja uma decisão com evidência por trás, não uma esperança.

Prática 7: Proteja ações destrutivas com um humano

Separe ferramentas de leitura de ferramentas de escrita e coloque um gate de confirmação humana em qualquer coisa destrutiva. As anotações de ferramentas da especificação MCP existem exatamente para isso: destructiveHint marca ferramentas que realizam atualizações destrutivas, e openWorldHint sinaliza ferramentas que tocam sistemas externos, para que clientes possam pedir confirmação antes de executar. Use-as.

O modo de falha não é hipotético. Laurent Kubaski documentou um caso, em seu relatório de tool calling de julho de 2025 com o relatório original linkado, onde um usuário pediu ao Copilot no Excel para agir na linha 4 e o agente agiu na linha 8. Nenhum gate de confirmação estava entre a linha errada e a escrita. A correção é o padrão que a AWS documenta para Bedrock Agents: o agente prepara a ação, retorna para aprovação e executa somente depois que um humano confirma. O Cursor faz o mesmo para edições de arquivos. Escopo de credenciais para somente leitura quando leitura é tudo que a tarefa precisa, e trate gates de confirmação como parte da sua superfície de injeção, o tópico do nosso guia de prevenção de prompt injection.

Prática 8: Rode um loop de avaliação a cada mudança de ferramenta

Rode uma pequena suíte de avaliação antes e depois de cada mudança de ferramenta, e leia as métricas em uma ordem fixa. O guia de otimização da Paragon propõe um quadro de quatro métricas que vale adotar:

O cookbook de avaliação de ferramentas da Anthropic, construído sobre avaliações reais de MCP do Slack e Asana, mostra como tarefas de avaliação boas e ruins se parecem:

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Nossa interpretação, rotulada como tal: os números publicados dão a ordem de trabalho. Verifique a corretude de ferramenta primeiro, porque as próprias medições da Anthropic mostram que mudanças de descrição e nomenclatura a movem diretamente (a reescrita de 206 para 72 tokens, a descoberta de alucinação UUID-para-nome), e deixe a eficiência de tarefa para o final, já que ela reflete principalmente falhas que as três primeiras métricas já capturaram. Para a suíte inicial, projete 15-30 tarefas, duas ou três por ferramenta, cada uma com uma única chamada esperada e uma condição binária de aprovação. Esse tamanho é suficiente para capturar uma regressão de uma reescrita de descrição sem uma semana de rotulagem, e lemos a configuração de Slack e Asana do cookbook como evidência de que uma suíte tão pequena é o ponto de partida pretendido, não um atalho. A mecânica mais profunda está no nosso guia de avaliação de agentes IA em produção, e se seus resultados de avaliação dizem que as ferramentas estão boas mas a orquestração não, é quando revisitar sua escolha de framework contra os melhores frameworks de agentes IA.

Tool calling em agentes vs MCP: qual a diferença?

MCP é um padrão de transporte e registro, não uma camada de confiabilidade, então as mesmas oito práticas se aplicam seja suas ferramentas chegando via MCP ou definidas inline. Tool calling nativo é o contrato modelo-provedor: como o modelo emite um tool_call e lê um tool_result. MCP padroniza como ferramentas chegam ao modelo; não faz nada sobre se o modelo escolhe a certa.

Um servidor MCP que expõe uma ferramenta chamada search com a descrição "searches things" falha identicamente a uma função inline definida da mesma forma. Corrija a definição, depois se preocupe com o transporte. Nosso guia de Model Context Protocol cobre o lado do protocolo de ponta a ponta.

Como a Techsy aplica estas oito práticas

Em cada build de agente para cliente, aplicamos três delas antes de qualquer outra coisa ir ao ar: descrições escritas como instruções (Prática 1), gates de validação em cada ferramenta de escrita (Prática 6) e uma suíte de avaliação que roda antes do deploy, não depois de um incidente (Prática 8). Essas três cobrem chamadas de ferramenta errada, chamadas de argumentos errados e as regressões que reintroduzem ambas, que é onde cada incidente de agente em produção que já depuramos começou. As outras cinco práticas seguem conforme o agente cresce. Se seu agente passou da fase de demo e está escolhendo as ferramentas erradas, agende uma consulta gratuita e diremos qual das oito corrigir primeiro.

Sobre o Autor

Mert Batur é Co-Fundador da Techsy.io, onde a equipe entrega agentes IA, sistemas de automação e pipelines de voz/SDR para clientes B2B. Ele escreve sobre o stack de tooling LLM que a equipe Techsy realmente usa em produção. Conecte-se no LinkedIn.

Perguntas Frequentes

O que é tool calling em agentes?

Tool calling em agentes é o mecanismo onde um LLM decide invocar uma função externa, emite um tool_call estruturado e espera seu código retornar um tool_result sobre o qual ele possa raciocinar. É o que transforma um modelo de chat em um agente que consegue consultar bancos de dados, chamar APIs e executar ações: o modelo escolhe a ferramenta e os argumentos, seu executor os roda.

Como funciona o loop de tool calling em agentes?

O loop tem cinco etapas: a requisição do usuário chega ao modelo, o modelo seleciona uma ferramenta e escreve um tool_call, seu executor o roda, um tool_result retorna ao modelo e o modelo responde ou emite outra chamada. Esse ciclo se repete até a tarefa terminar. Os quatro modos de falha neste guia cada um vive em uma etapa específica deste loop.

Por que meu agente escolhe a ferramenta errada?

Geralmente porque duas ferramentas se sobrepõem e suas descrições não dizem qual é qual. O modelo seleciona apenas por nomes e descrições, então "gets a user" versus "finds users" parece intercambiável. Corrija com linhas de exclusão ("do NOT use to search"), nomes com namespace e menos ferramentas em contexto. O teste de quatro modelos de Kubaski mostrou que até modelos fortes erram a rota em listas ambíguas.

Como forço um agente de tool calling a estruturar sua saída?

Restrinja o schema, não o prompt. Use enums para campos limitados, arrays de required para qualquer coisa que a tarefa precisa e objetos planos em vez de aninhados. Para a resposta final em vez da chamada de ferramenta, recursos de provedor como structured outputs da OpenAI e modos tool-choice da Anthropic forçam uma forma específica. Nosso guia de structured outputs cobre ambos os caminhos com código.

Tool calling em agentes vs MCP: qual a diferença?

Tool calling nativo é o contrato entre seu código e um provedor de modelo: o formato de mensagem tool_call e tool_result. MCP é uma camada de protocolo que padroniza como ferramentas são descobertas e entregues a qualquer cliente compatível. MCP muda o encanamento, não a confiabilidade. Uma ferramenta mal descrita falha da mesma forma por qualquer caminho, como nosso guia de Model Context Protocol explica.

Quantas ferramentas são demais para um agente LLM?

Trate 5-10 ferramentas por agente como uma faixa de trabalho, não uma lei. A precisão de seleção degrada conforme a lista visível cresce, especialmente quando nomes ou descrições se sobrepõem. A correção não é um modelo maior, mas filtragem: carregue apenas o subconjunto que a tarefa atual precisa, usando uma divisão planner-worker. Coloque namespace em tudo para que duas integrações nunca exponham ambas um search simples.

Qual o melhor modelo para tool calling?

Não existe uma resposta única, e benchmarks publicados envelhecem mal neste espaço. Modelos frontier da OpenAI, Anthropic e Google todos passam em tarefas básicas de uso de ferramentas, enquanto modelos menores pareados com ferramentas bem projetadas frequentemente completam tarefas quase tão frequentemente por uma fração do custo de tokens. Construa a suíte de avaliação de 15-30 tarefas da Prática 8 e teste candidatos contra suas próprias ferramentas.

Como reduzo o custo de tokens do tool calling?

Corte o que volta. Retorne resultados concisos e de alto sinal em vez de payloads brutos de API: a Anthropic documentou um corte de 206 para 72 tokens de uma única mudança de response_format. Resolva UUIDs para nomes, descarte campos que o modelo nunca usa e lembre que cada resultado de ferramenta re-entra na janela de contexto em cada turno seguinte. Menos chamadas, via ferramentas atômicas, remove resultados inteiros da conta.

Como avalio a qualidade do tool calling?

Pontue quatro métricas em ordem: corretude de ferramenta (ferramenta certa?), precisão de entrada (argumentos válidos?), conclusão de tarefa (objetivo alcançado?) e eficiência de tarefa (contagem de tokens e chamadas?). Escreva 15-30 tarefas, cada uma esperando uma chamada específica com argumentos verificáveis e uma condição binária de aprovação. Rode a suíte antes e depois de cada mudança de ferramenta para que uma reescrita de descrição nunca vá ao ar sem medição.

Conclusão

Diagnostique antes de otimizar. Seu agente escolhe a ferramenta errada por uma de quatro razões, e três das oito práticas acima, descrições, schemas planos e filtragem, corrigem as falhas de seleção que causam a maioria dos incidentes em produção. Comece por aí, porque custam uma tarde e são a razão pela qual este problema é corrigível. Mantenha erros de validação informativos, proteja qualquer coisa destrutiva com um humano e rode o loop de avaliação a cada mudança para que você meça antes de trocar modelos. O problema de ferramenta errada não é um problema de modelo. É um problema de design de ferramentas, e o design é seu.