Ver Como um Agente: O Que o Design de Ferramentas do Claude Code Revela

Thariq, da equipe do Claude Code na Anthropic, publicou uma thread sobre design de ferramentas para agentes de IA. O conteúdo é valioso por um motivo específico: é evidência de primeira mão. A equipe que constrói a ferramenta está documentando o que aprendeu sobre como modelos interagem com interfaces de ferramentas.

Quatro lições. Cada uma revela algo sobre como o design de ferramentas molda o comportamento de agentes em produção.

Lição 1: Ferramentas são interfaces cognitivas, não APIs

A equipe precisava que o Claude fizesse perguntas ao usuário durante a execução. Parece simples. Não foi.

Primeira tentativa: adicionaram um parâmetro no ExitPlanTool, uma ferramenta existente que já servia para encerrar o plano de execução. A ideia era econômica: reutilizar uma interface em vez de criar outra. O resultado foi que o modelo confundia sistematicamente os dois propósitos. Planejar a saída e formular perguntas são operações cognitivas distintas. Empacotá-las juntas forçou o modelo a processar intenções conflitantes.

Segunda tentativa: formato markdown modificado, sem ferramenta dedicada. Frases extras apareciam. Opções de resposta sumiam. A falta de estrutura formal gerou inconsistência.

Terceira tentativa: ferramenta dedicada AskUserQuestion com output estruturado. Funcionou. Cada campo tinha um propósito claro. O modelo sabia exatamente o que preencher.

O insight aqui vai além de “use ferramentas separadas”. Ferramentas não são apenas mecanismos de ação. São molduras cognitivas. Quando você projeta uma ferramenta, está definindo como o modelo organiza seu raciocínio sobre aquela tarefa. Uma ferramenta com propósitos múltiplos não é apenas confusa para o usuário. É confusa para o modelo.

A equipe do Azure SRE Agent chegou a conclusão semelhante por outro caminho. Começaram com mais de 100 ferramentas especializadas e consolidaram em cerca de 5 ferramentas CLI amplas. Descobriram que handoffs acima de 4 tinham taxa de falha quase total. Como exploramos em Context Engineering para Agentes de IA, dar ao modelo menos escolhas, mais limpas, gera melhor comportamento que maximizar opções.

A convergência é reveladora. Uma equipe começou com ferramentas demais e reduziu. Outra começou com ferramentas de menos e separou. Ambas convergiram no mesmo princípio: cada ferramenta deve representar uma única intenção cognitiva.

Lição 2: Ferramentas que funcionam hoje podem restringir amanhã

O Claude Code originalmente usava TodoWrite para tracking de tarefas. Funcionava. O modelo registrava itens, acompanhava progresso, mantinha organização. Lembretes do sistema a cada 5 turnos reforçavam o comportamento.

Dois problemas surgiram com o tempo. Primeiro: conforme os modelos melhoraram, os lembretes que antes ajudavam passaram a restringir. O modelo seguia a lista rigidamente em vez de adaptá-la quando o contexto mudava. Os guardrails viraram gaiola.

Segundo: quando subagentes entraram em cena (especialmente com o Opus 4.5), a ferramenta não suportava coordenação. Um Todo compartilhado não permite que agentes paralelos atualizem dependências entre tarefas.

A solução foi uma Task Tool com suporte a dependências, atualizações entre subagentes e capacidade de alterar ou deletar tarefas. Ferramentas diferentes para capacidades diferentes do modelo.

Isso levanta uma questão incômoda para qualquer equipe que constrói sistemas agênticos. Suas ferramentas atuais foram projetadas para as capacidades de qual versão do modelo? Quando o modelo melhora (e melhora rápido), as ferramentas que facilitavam o trabalho podem se tornar as estruturas que impedem o modelo de usar suas novas capacidades.

Não é um problema teórico. É um problema de operações. Requer revisão periódica da interface de ferramentas, não apenas do prompt.

Lição 3: De RAG para busca ativa (e os dados que complicam)

A evolução da busca no Claude Code seguiu três estágios.

RAG (Retrieval-Augmented Generation): poderoso, mas frágil. Exigia indexação prévia. O contexto era dado ao modelo, não encontrado por ele. Qualquer mudança no repositório invalidava o índice.

Grep e glob: o modelo busca e constrói seu próprio contexto. Mais lento, mas mais adaptável. O modelo desenvolve um entendimento do repositório ao navegar por ele.

Skills como progressive disclosure: documentação organizada em camadas. O modelo lê um arquivo raiz que aponta para outros arquivos relevantes. Busca aninhada, em várias camadas.

Thariq descreve essa evolução como evidência de que modelos passaram de “não conseguir construir seu próprio contexto” para “busca aninhada em várias camadas” em um ano.

Os dados da Vercel complicam essa narrativa. Em suas avaliações de janeiro de 2026, skills com comportamento padrão atingiram apenas 53% de aprovação, idêntico a não ter documentação alguma. Skills com instruções explícitas chegaram a 79%. AGENTS.md (contexto passivo) atingiu 100%. Como analisamos em Contexto Passivo Vence, o problema de ativação é real: em 56% dos casos, agentes nunca invocaram o skill que precisavam.

Isso não invalida a tese da Anthropic sobre progressive disclosure. Mas adiciona uma condição importante. Progressive disclosure funciona quando o modelo sabe que precisa buscar algo. Para conhecimento que o modelo não sabe que desconhece, contexto passivo continua sendo mais confiável.

A própria Anthropic reconhece isso implicitamente. O Tool Search do Claude Code (que permite buscar ferramentas sob demanda em vez de carregar todas no contexto) reduziu uso de contexto em 85% e aumentou precisão de 49% para 74% no Opus 4. Mas note: isso funciona porque o modelo já sabe que precisa de uma ferramenta. O gatilho de ativação é claro.

Lição 4: Expandir capacidades sem adicionar ferramentas

O Claude Code tem aproximadamente 20 ferramentas. A barra para adicionar novas é alta. Cada ferramenta adicional é custo cognitivo no contexto do modelo.

O problema: o Claude não sabia sobre si mesmo. Não tinha acesso à documentação do Claude Code. Adicionar tudo ao system prompt causaria “context rot” (degradação de atenção conforme o prompt cresce). Linkar para os docs carregava informação demais.

A solução: um subagente dedicado (Guide Agent) com instruções específicas sobre como navegar a documentação. Sem nova ferramenta. Sem contexto adicional no prompt principal. O Guide Agent é invocado quando necessário, traz a informação relevante, e o contexto do agente principal permanece limpo.

Isso é progressive disclosure aplicado à arquitetura do agente, não apenas ao conteúdo. Em vez de sobrecarregar o agente principal com conhecimento sobre tudo, delegue domínios de conhecimento para subagentes especializados. Como discutimos em Agentes Não São Ferramentas, a distinção entre o padrão tool e o padrão agent importa. O Guide Agent não é uma ferramenta que retorna dados. É um agente que raciocina sobre qual informação é relevante.

O que os dados dizem (e o que a thread não diz)

A thread de Thariq é valiosa como evidência de primeira mão. Mas falta algo: métricas.

Nenhuma das quatro lições vem acompanhada de taxas de conclusão, comparações A/B, ou taxas de erro antes e depois. A equipe do Azure SRE Agent publicou resultados quantificados. A Vercel publicou taxas de aprovação por abordagem. A thread do Claude Code opera no registro qualitativo.

A frase “tool design is an art, not a science” aparece como princípio orientador. É uma afirmação conveniente para quem projeta ferramentas por intuição. Mas o ecossistema de avaliação de agentes está tornando design de ferramentas cada vez mais empírico. Chamadas programáticas de ferramentas (programmatic tool calling) reduzem consumo de tokens em 37%. Tool Search melhora precisão em 25 pontos percentuais. Esses são resultados de ciência, não de arte.

Existe também uma tensão comercial inevitável. Cada decisão de design que a equipe do Claude Code documenta é, simultaneamente, uma lição de engenharia e marketing do produto. A thread demonstra a sofisticação do Claude Code enquanto ensina sobre design de ferramentas. Isso não invalida as lições. Mas exige que o leitor separe o insight técnico da narrativa promocional.

Três princípios para quem constrói

Se você está projetando ferramentas para agentes de IA, a evidência combinada (Claude Code, Azure SRE, Vercel) converge em três princípios:

Uma ferramenta, uma intenção cognitiva. Não empacote operações distintas na mesma interface. O modelo vai confundir os propósitos. Se duas ações exigem raciocínio diferente, precisam de ferramentas diferentes. Isso vale mesmo que pareça “desperdício” ter ferramentas separadas. Como documentamos em AI Agents Have Opinions, modelos têm preferências reais sobre como interfaces são estruturadas.

Revise ferramentas quando o modelo muda. Guardrails que ajudavam modelos anteriores podem restringir modelos mais capazes. Inclua revisão de interface de ferramentas no seu ciclo de atualização de modelos. Não apenas prompts.

Meça a taxa de ativação. Se uma ferramenta ou skill precisa ser invocada sob demanda, meça com que frequência o modelo realmente a invoca. Se a taxa é baixa, o design está falhando, independente de quão elegante a ferramenta seja.

Design de ferramentas para agentes é, no fundo, empatia com o comportamento do modelo. Não se trata de construir a interface mais poderosa. Trata-se de construir a interface que o modelo consegue usar de forma confiável, dadas suas capacidades e limitações atuais.

A equipe do Claude Code está aprendendo isso iterativamente. As lições são reais. Os dados de outras equipes acrescentam nuance. E a disciplina, aos poucos, deixa de ser “arte” para virar engenharia.

Fontes

Thariq. “Lessons from Building Claude Code: Seeing like an Agent.” Março 2026.
Microsoft. “Context Engineering Lessons from Building Azure SRE Agent.” 2026.
Vercel. “AGENTS.md Outperforms Skills in Our Agent Evals.” Janeiro 2026.
Anthropic. “Introducing Advanced Tool Use on Claude.” 2026.
Anthropic. “Tool Search and Programmatic Tool Calling.” 2026.

Victorino Group ajuda organizações a projetar sistemas de agentes de IA governados que escalam: contato@victorino.com.br | www.victorino.com.br