Domínio 2 — Tool Design & MCP Integration · Lição 1 de 6

Anatomia de uma ferramenta e descrições que funcionam

Objetivos de aprendizagem

• Identificar os campos de uma definição de ferramenta: name, description, input_schema e strict.
• Explicar por que a description é o mecanismo primário de seleção de ferramenta pelo modelo — e por que descrições mínimas causam seleção não confiável.
• Escrever descrições que incluem formatos de entrada, exemplos de consulta, edge cases e fronteiras ("use esta ferramenta quando... não use quando...").
• Diagnosticar misrouting causado por descrições ambíguas ou sobrepostas e corrigi-lo renomeando ou dividindo ferramentas genéricas.
• Reconhecer quando instruções sensíveis a palavras-chave no system prompt sobrepõem descrições bem escritas.

Os quatro campos de uma definição de ferramenta

Toda ferramenta definida pelo usuário na Claude API tem três campos obrigatórios e um opcional importante:

A descrição é o mecanismo primário de seleção

O modelo não lê seu código-fonte nem sabe o que o backend faz: ele escolhe a ferramenta lendo as descrições disponíveis e comparando-as com a intenção do usuário. Descrições mínimas como "Recupera informações do cliente" e "Recupera detalhes do pedido" não dão contexto suficiente para diferenciar duas ferramentas parecidas — o resultado é seleção não confiável, observável em produção como misrouting intermitente.

Uma descrição eficaz cobre quatro elementos:

• Formatos de entrada aceitos — ex.: "aceita IDs de pedido no formato ORD-XXXXX; não aceita nomes de clientes".
• Exemplos de consulta — ex.: "use para perguntas como 'onde está meu pedido #12345?'".
• Edge cases — ex.: "retorna lista vazia quando o pedido ainda não foi faturado".
• Fronteiras — quando usar esta ferramenta versus alternativas parecidas: "para dados cadastrais do cliente, use get_customer, não esta ferramenta".

Overlap entre ferramentas causa misrouting

Um sintoma clássico do exame: duas ferramentas com descrições quase idênticas — analyze_content ("Analisa conteúdo") e analyze_document ("Analisa documentos") — e o agente escolhendo a errada em parte das requisições. O problema não é o modelo: é que as descrições não oferecem nenhum critério de decisão. Três correções, em ordem crescente de esforço:

1. Enriquecer descrições com formatos, exemplos e fronteiras (primeiro passo de baixo esforço e alto retorno).
2. Renomear a ferramenta para eliminar overlap funcional — ex.: renomear analyze_content para extract_web_results com descrição específica de conteúdo web.
3. Dividir ferramentas genéricas em ferramentas de propósito específico com contratos de entrada/saída bem definidos — ex.: dividir analyze_document em extract_data_points, summarize_content e verify_claim_against_source.

O system prompt pode sobrepor descrições

Mesmo com descrições perfeitas, instruções sensíveis a palavras-chave no system prompt criam associações indesejadas. Exemplo: um system prompt que diz "sempre que o usuário mencionar documento, use analyze_document" fará o agente chamar essa ferramenta até para "documento fiscal de um pedido", ignorando a ferramenta correta. Ao diagnosticar misrouting, revise o system prompt em busca de gatilhos por palavra-chave antes de reescrever as descrições — a instrução do system prompt tem forte autoridade sobre a decisão do modelo.

Exemplo completo em Python

Ferramenta com descrição completa (formato de entrada, exemplos, edge case, fronteira) e strict: true:

import anthropic

client = anthropic.Anthropic()

lookup_order = {
    "name": "lookup_order",
    "description": (
        "Busca o status e os itens de um pedido pelo ID. "
        "Formato de entrada: IDs no padrao ORD-XXXXX (ex.: ORD-48211); "
        "nao aceita nomes de clientes nem e-mails. "
        "Use para perguntas como 'onde esta meu pedido ORD-48211?'. "
        "Edge case: pedidos ainda nao faturados retornam items=[] com "
        "status='pending' — isso e um resultado valido, nao um erro. "
        "Fronteira: para dados cadastrais do cliente (nome, endereco), "
        "use get_customer em vez desta ferramenta."
    ),
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "ID do pedido no formato ORD-XXXXX",
            }
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    thinking={"type": "adaptive"},
    tools=[lookup_order],
    messages=[{"role": "user", "content": "Onde esta meu pedido ORD-48211?"}],
)

for block in response.content:
    if block.type == "tool_use":
        print(block.name, block.input)

Pegadinhas da prova

• Distrator típico: "adicione few-shot examples no system prompt" como primeiro passo para misrouting entre ferramentas parecidas. Errado: descrições são o mecanismo primário de seleção; enriquecê-las é a correção de raiz, com menos overhead de tokens.
• Distrator típico: "implemente uma camada de roteamento que pré-seleciona a ferramenta por keywords". Over-engineering: contorna a compreensão de linguagem natural do modelo em vez de corrigir as descrições.
• Distrator típico: "consolide as duas ferramentas em uma só genérica". Válido como decisão arquitetural em alguns casos, mas nunca é o "primeiro passo" — e frequentemente piora o contrato de entrada.
• Pegadinha: descrições impecáveis mas misrouting persistente → procure instruções por palavra-chave no system prompt que sobrepõem as descrições.
• Pegadinha: strict: true garante argumentos válidos contra o schema, mas não garante que a ferramenta certa foi escolhida — seleção continua dependendo da descrição.

Resumo em 5 linhas

Documentação oficial

• Tool use — Overview
• Implement tool use (best practices de descrições)
• Structured outputs e strict tool use

Questões de fixação