Design de Ferramentas para Agentes

O que Design de Ferramentas para Agentes faz?

Projete cada ferramenta como um contrato entre um sistema determinístico e um agente não-determinístico. Diferentemente de APIs voltadas para humanos, as ferramentas voltadas para agentes devem tornar o contrato inequívoco apenas por meio da descrição: os agentes inferem a intenção a partir das descrições e geram chamadas que devem corresponder aos formatos esperados. Toda ambiguidade se torna um modo de falha potencial que nenhuma engenharia de prompt pode corrigir.

A unidade de trabalho para esta skill é uma única ferramenta ou um catálogo de ferramentas. Decisões sobre o formato do projeto, arquitetura de pipeline, adequação do modelo à tarefa e custo no nível do projeto pertencem a project-development. Decidir se deve introduzir subagentes pertence a multi-agent-patterns. Esta skill é responsável pela camada de interface que conecta o código determinístico ao agente.

Quando Ativar

Ative esta skill quando a unidade de trabalho for uma ferramenta:

• Escrever uma nova descrição, schema ou formato de resposta de ferramenta.
• Depurar casos em que o agente escolheu a ferramenta errada ou gerou chamadas malformadas.
• Consolidar um catálogo de ferramentas sobreposto (o clássico caso de "temos 17 ferramentas, o agente erra metade das vezes").
• Projetar mensagens de erro acionáveis para que o agente possa se autocorrigir.
• Nomear ferramentas e parâmetros de forma consistente em todo um catálogo (namespacing MCP, nomenclatura verbo-substantivo).
• Avaliar uma ferramenta de terceiros em relação ao princípio de consolidação antes de adicioná-la.

Não ative esta skill para trabalhos adjacentes de outras skills:

• Decidir se o projeto deve usar LLMs ou quais devem ser os estágios do pipeline: project-development.
• Decidir se deve dividir o trabalho entre subagentes ou executar um único agente com mais ferramentas: multi-agent-patterns.
• Reduzir o peso de tokens das saídas das ferramentas no nível da trajetória (mascaramento de observação, escolha de formato em escala): context-optimization.

Conceitos Principais

Projete ferramentas em torno do princípio de consolidação: se um engenheiro humano não consegue dizer definitivamente qual ferramenta deve ser usada em uma determinada situação, um agente não pode fazer melhor. Reduza o conjunto de ferramentas até que cada uma tenha um propósito inequívoco, porque os agentes selecionam ferramentas comparando descrições, e qualquer sobreposição introduz erros de seleção.

Trate toda descrição de ferramenta como engenharia de prompt que molda o comportamento do agente. A descrição não é documentação para humanos — ela é injetada no contexto do agente e direciona diretamente o raciocínio. Escreva descrições que respondam o que a ferramenta faz, quando usá-la e o que ela retorna, porque essas três perguntas são exatamente o que os agentes avaliam durante a seleção de ferramentas.

Tópicos Detalhados

A Interface Ferramenta-Agente

Ferramentas como Contratos Projete cada ferramenta como um contrato autocontido. Quando humanos chamam APIs, eles leem a documentação, entendem as convenções e fazem solicitações apropriadas. Os agentes devem inferir o contrato inteiro a partir de um único bloco de descrição. Torne o contrato inequívoco incluindo exemplos de formato, padrões esperados e restrições explícitas. Não omita nada que um chamador precise saber, porque os agentes não podem fazer perguntas esclarecedoras antes de fazer uma chamada.

Descrição da Ferramenta como Prompt Escreva descrições de ferramentas sabendo que elas carregam diretamente no contexto do agente e, coletivamente, orientam o comportamento. Uma descrição vaga como "Pesquisar no banco de dados" com nomes de parâmetros enigmáticos força o agente a adivinhar — e adivinhar produz chamadas incorretas. Em vez disso, inclua contexto de uso, exemplos de formato de parâmetros e padrões sensatos. Cada palavra na descrição ajuda ou atrapalha a precisão da seleção de ferramentas.

Namespacing e Organização Atribua namespaces a ferramentas sob prefixos comuns à medida que a coleção cresce, porque os agentes se beneficiam do agrupamento hierárquico. Quando um agente precisa de operações de banco de dados, ele roteia para o namespace db_*; quando precisa de interações web, roteia para web_*. Sem namespacing, os agentes devem avaliar todas as ferramentas em uma lista plana, o que degrada a precisão da seleção à medida que o número cresce.

O Princípio de Consolidação

Ferramentas Únicas e Abrangentes Construa ferramentas únicas e abrangentes em vez de várias ferramentas estreitas que se sobrepõem. Em vez de implementar listar_usuarios, listar_eventos e criar_evento separadamente, implemente agendar_evento que encontra disponibilidade e agenda em uma única chamada. A ferramenta abrangente lida com o fluxo de trabalho completo internamente, removendo o fardo do agente de encadear chamadas na ordem correta.

Por que a Consolidação Funciona Aplique a consolidação porque os agentes têm contexto e atenção limitados. Cada ferramenta na coleção compete por atenção durante a seleção, cada descrição consome tokens do orçamento de contexto e a funcionalidade sobreposta cria ambiguidade. A consolidação elimina descrições redundantes, remove a ambiguidade de seleção e reduz o conjunto efetivo de ferramentas. O estudo de caso d0 da Vercel é um exemplo concreto de redução de ferramentas especializadas em um conjunto menor de ferramentas primitivas com melhores resultados medidos (claim-tool-design-vercel-d0-reduction).

Quando Não Consolidar Mantenha as ferramentas separadas quando elas têm comportamentos fundamentalmente diferentes, servem a contextos diferentes ou devem ser chamáveis independentemente. A consolidação excessiva cria um problema diferente: uma única ferramenta com muitos parâmetros e modos se torna difícil para os agentes parametrizarem corretamente.

Redução Arquitetônica

Leve o princípio de consolidação ao seu extremo lógico, removendo a maioria das ferramentas especializadas em favor de capacidades primitivas e de uso geral. Evidências de produção mostram que essa abordagem pode superar arquiteturas sofisticadas com múltiplas ferramentas.

O Padrão de Agente de Sistema de Arquivos Forneça acesso direto ao sistema de arquivos por meio de uma única ferramenta de execução de comando em vez de construir ferramentas personalizadas para exploração de dados, consulta de schema e validação de consultas. O agente usa utilitários Unix padrão (grep, cat, find, ls) para explorar e operar no sistema. Isso funciona porque sistemas de arquivos são uma abstração comprovada que os modelos entendem profundamente, ferramentas padrão têm comportamento previsível, os agentes podem encadear primitivas de forma flexível em vez de serem limitados a fluxos de trabalho predefinidos, e boa documentação em arquivos substitui ferramentas de sumarização.

Quando a Redução Supera a Complexidade Escolha a redução quando a camada de dados for bem documentada e consistentemente estruturada, o modelo tiver capacidade de raciocínio suficiente, ferramentas especializadas estiverem restringindo em vez de permitir o modelo, ou mais tempo for gasto mantendo a estrutura de suporte do que melhorando os resultados. Evite a redução quando os dados subjacentes forem confusos ou mal documentados, o domínio exigir conhecimento especializado que o modelo não possui, restrições de segurança devem limitar as ações do agente, ou as operações se beneficiarem genuinamente de fluxos de trabalho estruturados.

Construa para Modelos Futuros Projete arquiteturas mínimas que se beneficiem das melhorias do modelo, em vez de arquiteturas sofisticadas que travam as limitações atuais. Pergunte se cada ferramenta permite novas capacidades ou restringe o raciocínio que o modelo poderia realizar sozinho — ferramentas construídas como "guardrails" frequentemente se tornam passivos à medida que os modelos melhoram.

Veja Estudo de Caso de Redução Arquitetônica para evidências de produção.

Engenharia de Descrição de Ferramentas

Estrutura da Descrição Estruture toda descrição de ferramenta para responder a quatro perguntas:

1. O que a ferramenta faz? Declare exatamente o que a ferramenta realiza — evite linguagem vaga como "ajuda com" ou "pode ser usada para."
2. Quando deve ser usada? Especifique gatilhos diretos ("O usuário pergunta sobre preços") e sinais indiretos ("Precisa de taxas de mercado atuais").
3. Que entradas ela aceita? Descreva cada parâmetro com tipos, restrições, padrões e exemplos de formato.
4. O que ela retorna? Documente o formato de saída, estrutura, exemplos de resposta bem-sucedida e condições de erro.

Seleção de Parâmetros Padrão Defina padrões para refletir casos de uso comuns. Os padrões reduzem o fardo do agente, eliminando a especificação desnecessária de parâmetros e prevenindo erros de parâmetros omitidos. Escolha padrões que produzam resultados úteis sem exigir que o agente entenda todas as opções.

Otimização do Formato de Resposta

Ofereça opções de formato de resposta (concisa vs. detalhada) porque o tamanho da resposta da ferramenta impacta significativamente o uso do contexto. O formato conciso retorna apenas campos essenciais, adequado para confirmações. O formato detalhado retorna objetos completos, adequado quando o contexto completo impulsiona decisões. Documente quando usar cada formato na descrição da ferramenta para que os agentes aprendam a selecionar apropriadamente.

Design de Mensagens de Erro

Projete mensagens de erro para dois públicos: desenvolvedores depurando problemas e agentes se recuperando de falhas. Para agentes, toda mensagem de erro deve ser acionável — ela deve declarar o que deu errado e como corrigi-lo. Inclua orientação de nova tentativa para erros que podem ser repetidos, exemplos de formato corrigido para erros de entrada e campos específicos ausentes para solicitações incompletas. Um erro que diz apenas "falhou" fornece sinal de recuperação zero.

Schema de Definição de Ferramenta

Estabeleça um schema consistente em todas as ferramentas. Use o padrão verbo-substantivo para nomes de ferramentas (get_customer, create_order), nomes de parâmetros consistentes entre ferramentas (sempre customer_id, nunca às vezes id e às vezes identifier) e nomes de campos de retorno consistentes. A consistência reduz a carga cognitiva sobre os agentes e melhora a generalização entre ferramentas.

Design de Coleção de Ferramentas

Limite as coleções de ferramentas ao menor conjunto com propósitos não sobrepostos, porque a sobreposição de descrições causa confusão no modelo e mais ferramentas nem sempre levam a melhores resultados. Quando mais ferramentas são genuinamente necessárias, use namespacing para criar agrupamentos lógicos. Implemente mecanismos de seleção: agrupamento de ferramentas por domínio, dicas de seleção baseadas em exemplos e ferramentas guarda-chuva que roteiam para subferramentas especializadas.

Requisitos de Nomenclatura de Ferramentas MCP

Use sempre nomes de ferramentas totalmente qualificados com o MCP (Model Context Protocol) para evitar erros de "ferramenta não encontrada".

Formato: NomeDoServidor:nome_da_ferramenta

# Correto: Nomes totalmente qualificados
"Use a ferramenta BigQuery:bigquery_schema para recuperar schemas de tabelas."
"Use a ferramenta GitHub:create_issue para criar issues."

# Incorreto: Nomes não qualificados
"Use a ferramenta bigquery_schema..."  # Pode falhar com vários servidores

Sem o prefixo do servidor, os agentes podem falhar ao localizar ferramentas quando vários servidores MCP estão disponíveis. Estabeleça convenções de nomenclatura que incluam o contexto do servidor em todas as referências de ferramentas.

Usando Agentes para Otimizar Ferramentas

Alimente falhas observadas de ferramentas de volta para um agente diagnosticar problemas e melhorar descrições. Trate ganhos de eficiência relatados como específicos da carga de trabalho até serem reproduzidos no catálogo de ferramentas alvo.

O Padrão de Agente de Teste de Ferramentas:

def optimize_tool_description(tool_spec, failure_examples):
    """
    Use um agente para analisar falhas de ferramentas e melhorar descrições.

    Processo:
    1. O agente tenta usar a ferramenta em diversas tarefas
    2. Colete modos de falha e pontos de atrito
    3. O agente analisa falhas e propõe melhorias
    4. Teste descrições melhoradas nas mesmas tarefas
    """
    prompt = f"""
    Analise esta especificação de ferramenta e as falhas observadas.

    Ferramenta: {tool_spec}

    Falhas observadas:
    {failure_examples}

    Identifique:
    1. Por que os agentes estão falhando com esta ferramenta
    2. Que informações estão faltando na descrição
    3. Que ambiguidades causam uso incorreto

    Proponha uma descrição de ferramenta melhorada que resolva esses problemas.
    """

    return get_agent_response(prompt)

Isso cria um ciclo de feedback: agentes usando ferramentas geram dados de falha, que os agentes então usam para melhorar as descrições das ferramentas, o que reduz falhas futuras.

Testando o Design de Ferramentas

Avalie os designs de ferramentas contra cinco critérios: ausência de ambiguidade, completude, capacidade de recuperação, eficiência e consistência. Teste apresentando solicitações de agente representativas e avaliando as chamadas de ferramenta resultantes em relação ao comportamento esperado.

Orientação Prática

Estrutura de Seleção de Ferramentas

Ao projetar coleções de ferramentas:

1. Identifique fluxos de trabalho distintos que os agentes devem realizar
2. Agrupe ações relacionadas em ferramentas abrangentes
3. Garanta que cada ferramenta tenha um propósito claro e inequívoco
4. Documente casos de erro e caminhos de recuperação
5. Teste com interações reais de agente

Checklist de Auditoria de Ferramentas

Use este checklist para toda ferramenta antes de adicioná-la a um agente:

1. Nome: verbo-substantivo, com namespacing se o catálogo tiver vários domínios.
2. Descrição: declara o que a ferramenta faz, quando usá-la e o que ela retorna.
3. Schema: todo parâmetro tem tipo, restrições, padrões e valores de exemplo.
4. Formato de retorno: payloads de sucesso e erro são documentados e legíveis por máquina.
5. Recuperação: cada erro diz ao agente o que mudar antes de tentar novamente.
6. Sobreposição: nenhuma outra ferramenta tem o mesmo cenário de ativação.
7. Decisão de consolidação: ferramentas estreitas adjacentes são mescladas, a menos que chamadas independentes sejam necessárias.
8. Impacto de token: respostas grandes suportam modo conciso ou modo de referência de arquivo.

Exemplos

Exemplo 1: Ferramenta Bem Projetada

def get_customer(customer_id: str, format: str = "concise"):
    """
    Recupera informações do cliente pelo ID.

    Use quando:
    - O usuário pergunta sobre detalhes específicos do cliente
    - Precisa de contexto do cliente para tomada de decisão
    - Verificando a identidade do cliente

    Args:
        customer_id: Formato "CUST-######" (ex.: "CUST-000001")
        format: "concise" para campos principais, "detailed" para registro completo

    Retorna:
        Objeto Cliente com os campos solicitados

    Erros:
        NOT_FOUND: ID do cliente não encontrado
        INVALID_FORMAT: ID deve corresponder ao padrão CUST-######
    """

Exemplo 2: Design de Ferramenta Ruim

Este exemplo demonstra várias antipadrões de design de ferramentas:

def search(query):
    """Pesquisar no banco de dados."""
    pass

Problemas com este design:

1. Nome vago: "search" é ambíguo — pesquisar o quê, para que propósito?
2. Parâmetros ausentes: Qual banco de dados? Que formato o query deve ter?
3. Nenhuma descrição de retorno: O que esta função retorna? Estrutura? Casos de erro?
4. Nenhum contexto de uso: Quando usar esta ferramenta vs. outras operações?
5. Nenhum padrão: O departamento de suporte tem schema diferente?

Referências

• Estudo de caso de redução: d0 da Vercel (claim-tool-design-vercel-d0-reduction)
• Estudo de Caso de Redução Arquitetônica
• Princípios MCP (Model Context Protocol)