Boas ferramentas fazem bons agentes.
Na era dos agentes, as ferramentas não são mais simples wrappers em torno de APIs tradicionais ou interfaces de função — elas são o fator decisivo para que um agente consiga concluir seu trabalho com eficiência. Para liberar o potencial dos agentes, precisamos repensar como as ferramentas são construídas. O desenvolvimento tradicional de software depende de lógica determinística, mas os agentes são não determinísticos: diante de uma entrada idêntica, podem produzir saídas diferentes. Projetar ferramentas para agentes exige, portanto, um novo paradigma — e não apenas como construí-las, mas como fazê-las performar no máximo. Um agente de IA é tão forte quanto as ferramentas que damos a ele. A questão é como fazer com que essas ferramentas entreguem tudo o que podem. O post de engenharia da Anthropic traça um caminho viável: anthropic.com/engineering/writing-tools-for-agents.
Depois de ler, você será capaz de: construir e testar protótipos de ferramentas; criar e executar avaliações abrangentes; e colaborar com agentes (como o Claude Code) para melhorar o desempenho do modelo automaticamente.
O Que É uma Ferramenta
Na computação, um sistema determinístico produz a mesma saída sempre que recebe a mesma entrada; um sistema não determinístico — um agente — pode responder de forma diferente sob condições iniciais idênticas. O desenvolvimento tradicional de software constrói contratos entre sistemas determinísticos: chame getWeather("NYC") mil vezes e ela retorna o clima de Nova York de mil maneiras idênticas. Mas uma ferramenta para modelos grandes é um novo tipo de software: um contrato entre um sistema determinístico e um agente não determinístico.
Exemplo: um usuário pergunta “devo levar um guarda-chuva hoje?”. O agente pode chamar a ferramenta de clima, pode responder por senso comum, pode primeiro fazer uma pergunta de esclarecimento (qual cidade, exatamente?). Às vezes ele alucinará; às vezes simplesmente não entenderá como usar a ferramenta. Escrever software para agentes exige, portanto, repensar o método a partir dos primeiros princípios: pare de escrever ferramentas e servidores MCP como funções ou APIs comuns, e projete-os especificamente para agentes.
Como Escrever Ferramentas
Primeiro, crie protótipos de ferramentas rapidamente e teste-os localmente. Depois, execute avaliações abrangentes para medir o impacto de cada mudança. Repita o ciclo de avaliar e melhorar com agentes até que o desempenho em tarefas reais seja forte.
Prototipagem. O tutorial usa a construção de agentes baseados em Claude como exemplo. Se você usar o Claude Code para escrever ferramentas, forneça ao Claude a documentação relevante — as bibliotecas, APIs ou SDKs de que suas ferramentas dependem, incluindo quaisquer SDKs de MCP. Documentação amigável a LLMs geralmente está disponível como um arquivo llms.txt nos sites de documentação oficiais. Envolva sua ferramenta em um servidor MCP local ou uma extensão de desktop (DXT) para conectá-la e testá-la no Claude Code ou no Claude Desktop. Para conectar um servidor MCP local ao Claude Code, execute claude mcp add <name> <command> [args...]; no Claude Desktop, use Configurações → Desenvolvedor ou Configurações → Extensões. Você também pode passar ferramentas diretamente para chamadas da API da Anthropic para testes programáticos. Em seguida, teste você mesmo para encontrar os pontos fracos.
Executando Avaliações
Gere tarefas de avaliação. Assim que o protótipo inicial existir, o Claude Code pode exercitar sua ferramenta e gerar dezenas de pares de prompt-resposta. Os prompts devem vir de cenários reais de uso contra fontes de dados e serviços reais — bases de conhecimento internas, microsserviços. Evite ambientes sandbox simplificados demais: eles não conseguem estressar a ferramenta sob condições genuinamente complexas. Tarefas de avaliação de alta qualidade frequentemente exigem muitas chamadas de ferramenta — às vezes dezenas. Boas tarefas se parecem com: “Agende uma reunião com a Jane na próxima semana para discutir nosso último projeto da Acme Corp. Anexe as notas da nossa última reunião de planejamento e reserve uma sala de conferência.” Ou: “O cliente de ID 9182 relata ter sido cobrado três vezes por uma única compra. Encontre todas as entradas de log relacionadas e determine se outros clientes foram afetados pelo mesmo problema.” Tarefas fracas se parecem com: “Agende uma reunião com [email protected] na próxima semana” ou “busque nos logs de pagamento purchase_complete e customer_id=9182.”
Cada prompt de avaliação deve vir em par com uma resposta ou resultado verificável. Seu verificador pode ser tão simples quanto uma comparação exata de strings contra uma ground truth ou tão avançado quanto um LLM julgando a resposta — mas evite verificadores excessivamente rígidos que rejeitam respostas corretas por causa de formatação, pontuação ou formulações alternativas válidas. Para cada par, você também pode especificar quais ferramentas o agente deve chamar, para medir se ele compreendeu o propósito de cada uma — mas, como múltiplos caminhos válidos podem resolver uma tarefa corretamente, evite especificar demais e superajustar a estratégia. Execute as avaliações programaticamente por meio de chamadas diretas à API do LLM, usando um loop de agente simples (um while loop alternando a API do LLM com chamadas de ferramentas), um loop por tarefa, com cada agente de avaliação recebendo seu prompt de tarefa e as ferramentas relevantes. Se você avaliar com o Claude, ative o pensamento intercalado para poder ver por que o agente chamou ou não ferramentas específicas. Além da precisão, colete outras métricas: tempo total de execução por chamada de ferramenta e por tarefa, contagem de chamadas de ferramenta, consumo total de tokens e taxas de erro das ferramentas.
Analise os resultados. O que os agentes omitem de suas respostas costuma ser mais revelador do que o que incluem — LLMs nem sempre articulam seu estado verdadeiro. Observe onde o agente trava ou fica confuso, e use esse feedback para localizar os pontos fracos da ferramenta. Revise as transcrições brutas (chamadas e respostas de ferramentas) para capturar comportamentos que nunca apareceram na cadeia de raciocínio do agente, e lembre-se de que seu agente de avaliação não necessariamente conhece a resposta correta ou a melhor estratégia. Analise também suas métricas de chamadas de ferramenta: muitas chamadas redundantes sugerem que os parâmetros de paginação ou limite de tokens precisam ser redesenhados; muitos erros de parâmetro inválido sugerem que a ferramenta precisa de descrições mais claras ou melhores exemplos de uso. E colabore com o agente: cole as transcrições de avaliação concatenadas no Claude Code — o Claude é excelente em analisar transcrições e pode refatorar grandes lotes de ferramentas em uma única passada.
Princípios para Escrever Ferramentas Eficazes
Escolha as ferramentas certas — mais ferramentas não significam melhores resultados. Um padrão comum: ferramentas que meramente encapsulam funcionalidades existentes de software ou endpoints de API, sem verificar se chamá-las sequer convém a um agente. A razão pela qual os agentes diferem do software tradicional são as affordances: eles percebem e usam ferramentas de forma completamente diferente. O contexto de um agente LLM é limitado — a informação que ele pode processar de uma vez — enquanto a memória do computador é barata e efetivamente infinita. Considere encontrar um contato em uma agenda: o software tradicional armazena e processa contatos uma a uma, verificando cada uma em sequência, de forma barata. Mas se a ferramenta de um agente retornar todos os contatos e ele tiver de lê-los token por token, ele queima seu precioso contexto em entradas irrelevantes. (Imagine encontrar um contato folheando a agenda página por página — busca por força bruta.) O caminho melhor e mais natural — para agentes e humanos — é saltar direto para a página relevante, em ordem alfabética.
Portanto, construa um pequeno número de ferramentas cuidadosamente projetadas para fluxos de trabalho de alto valor, alinhadas com suas tarefas de avaliação, e expanda gradualmente. No exemplo da agenda, implemente search_contacts ou message_contact em vez de um simples list_contacts. As ferramentas também podem consolidar — lidar com múltiplas operações discretas (ou chamadas de API) na camada subjacente, sob uma única chamada: retornando resultados com metadados relevantes anexados, ou completando tarefas de múltiplas etapas frequentemente encadeadas em uma única invocação. Exemplos: em vez de ferramentas separadas list_users, list_events e create_event, construa schedule_event, que encontra horários livres e reserva diretamente; em vez de read_logs, construa search_logs, retornando apenas as linhas relevantes com o contexto necessário; em vez de get_customer_by_id mais list_transactions mais list_notes, construa get_customer_context, agregando tudo o que é recente e relevante sobre um cliente de uma só vez. Cada ferramenta deve ter um propósito claro e distinto — permitindo que o agente decomponha e resolva tarefas como um humano faria com os mesmos recursos subjacentes, ao mesmo tempo em que reduz o espaço de contexto que os resultados intermediários consumiriam. Ferramentas demais, ou com funções sobrepostas, distraem o agente e obstruem estratégias eficientes. Um planejamento cuidadoso e seletivo do que não construir costuma trazer os maiores retornos.
Use namespaces em suas ferramentas. Os agentes podem se conectar a dezenas de servidores MCP e centenas de ferramentas, incluindo ferramentas escritas por outros desenvolvedores. Quando as funções se sobrepõem ou os propósitos se confundem, os agentes ficam confusos sobre qual ferramenta usar. Namespacing — agrupar ferramentas relacionadas sob um prefixo comum — delimita fronteiras claras; alguns clientes MCP fazem isso por padrão. Use namespace por serviço (asana_search, jira_search) ou por recurso (asana_projects_search, asana_users_search) para ajudar o agente a selecionar corretamente no momento certo. Nomear com prefixo versus sufixo performou de maneira diferente em avaliações de uso de ferramentas, então deixe seus resultados de avaliação decidirem. Pule esta etapa e o agente chamará a ferramenta errada, chamará a ferramenta certa com argumentos errados, chamará poucas ferramentas ou lidará mal com as respostas das ferramentas.
Retorne contexto significativo das ferramentas. As implementações de ferramentas devem retornar apenas informações de alto sinal, priorizando a relevância contextual sobre a flexibilidade, e evitando identificadores técnicos de baixo nível (uuid, 256px_image_url, mime_type). Campos como name, image_url e file_type são muito mais propensos a impulsionar as ações subsequentes do agente. Agentes lidam com nomes, termos e identificadores em linguagem natural dramaticamente melhor do que com os obscuros — simplesmente resolver UUIDs alfanuméricos arbitrários em linguagem semanticamente significativa e interpretável (mesmo um esquema de IDs a partir de zero) melhora mensuravelmente a precisão de recuperação do Claude e reduz alucinações. Onde o agente precisa de ambos — linguagem natural para entender, identificadores técnicos para acionar chamadas subsequentes (search_user(name='jane') → send_message(id=12345)) — exponha um parâmetro enum response_format simples, permitindo que o agente escolha respostas “concisas” ou “detalhadas”. Mais formatos adicionam flexibilidade, ao estilo GraphQL, deixando o agente escolher exatamente o que recebe. Em um exemplo medido, uma resposta detalhada de thread do Slack custou 206 tokens, enquanto a resposta concisa — apenas o conteúdo da thread, sem thread_ts ou IDs de canal — custou 72, cerca de um terço. O próprio formato da resposta (XML, JSON, Markdown) também afeta o desempenho nas avaliações: não há uma resposta única para todos os casos, porque LLMs são treinados com previsão do próximo token e performam melhor nos formatos que correspondem aos seus dados de treinamento — teste e escolha por tarefa e agente.
Otimize a eficiência de tokens nas respostas. A qualidade do contexto importa, mas a quantidade também. Para qualquer resposta de ferramenta que possa consumir um contexto substancial, combine paginação, seleção de intervalo, filtragem e/ou truncamento com valores de parâmetros padrão sensatos. O Claude Code limita as respostas das ferramentas a 25.000 tokens por padrão. Os comprimentos efetivos de contexto dos agentes crescerão ao longo do tempo — mas a necessidade de ferramentas eficientes em contexto nunca desaparecerá. Se você truncar, dê ao agente orientação prática: incentive estratégias eficientes de tokens diretamente, como várias buscas pequenas e direcionadas em uma tarefa de recuperação de conhecimento, em vez de uma varredura ampla única. E quando as chamadas de ferramenta produzem erros — falhas de validação de entrada, por exemplo — desenhe as respostas de erro como prompts em si, comunicando claramente melhorias específicas e acionáveis, em vez de códigos de erro opacos ou stack traces.
A Conclusão
O ponto mais profundo do guia é a reformulação em sua abertura: o design de ferramentas para agentes é design de contratos através de uma fronteira de determinismo, o que o torna uma disciplina genuinamente nova, e não desenvolvimento de API com sintaxe nova. O ciclo prático — prototipar localmente, avaliar programaticamente, analisar falhas, refatorar com a ajuda do próprio agente — transforma a qualidade das ferramentas de uma questão de intuição em uma questão de medição. E os princípios todos apontam em uma direção: respeite a janela de contexto do agente como o recurso mais escasso do sistema, porque cada token desnecessário retornado por uma ferramenta é atenção roubada da própria tarefa. As equipes que internalizarem isso — menos ferramentas, melhores nomes, respostas de alto sinal, avaliações mensuráveis — verão seus agentes melhorarem sem tocar em um único parâmetro do modelo. Essa é a revolução silenciosa da engenharia agêntica: às vezes, o caminho mais rápido para um agente mais inteligente é uma ferramenta melhor, não um modelo melhor.