Definir ferramentas

Pré-requisitos

• Familiaridade com a visão geral do uso de ferramentas
• Uma chave de API do Claude e uma configuração funcional de SDK ou cURL

Especificando ferramentas de cliente

As "client tools" (ferramentas de cliente) são especificadas no parâmetro de nível superior tools da requisição à API. Ferramentas de cliente com esquema da Anthropic, como as ferramentas bash e editor de texto, são declaradas por um type versionado por data; consulte a página de cada ferramenta, vinculada a partir da Referência de ferramentas, para ver os campos que ela aceita. As ferramentas de uso de computador e uso de navegador são conjuntos de ferramentas de cliente: uma única entrada sem name que declara um conjunto fixo de ferramentas membro. Uma definição de ferramenta definida pelo usuário inclui:

Para o conjunto completo de propriedades opcionais disponíveis em qualquer definição de ferramenta individual, incluindo cache_control, strict, defer_loading e allowed_callers, consulte a Referência de ferramentas. Uma entrada de conjunto de ferramentas de cliente aceita cache_control e allowed_callers na entrada e define defer_loading por membro; consulte Conjuntos de ferramentas de cliente.

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Prompt do sistema para uso de ferramentas

Quando você chama a API do Claude com o parâmetro tools, a API constrói um "system prompt" (prompt do sistema) especial a partir das definições de ferramentas, da configuração de ferramentas e de qualquer prompt do sistema especificado pelo usuário. O prompt construído é projetado para instruir o modelo a usar a(s) ferramenta(s) especificada(s) e fornecer o contexto necessário para que a ferramenta opere corretamente:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Melhores práticas para definições de ferramentas

Para obter o melhor desempenho do Claude ao usar ferramentas, siga estas diretrizes:

• Forneça descrições extremamente detalhadas. Este é, de longe, o fator mais importante no desempenho das ferramentas. Suas descrições devem explicar cada detalhe sobre a ferramenta, incluindo:
  • O que a ferramenta faz
  • Quando ela deve ser usada (e quando não deve)
  • O que cada parâmetro significa e como ele afeta o comportamento da ferramenta
  • Quaisquer ressalvas ou limitações importantes, como quais informações a ferramenta não retorna se o nome da ferramenta não for claro. Quanto mais contexto você puder dar ao Claude sobre suas ferramentas, melhor ele será em decidir quando e como usá-las. Procure escrever pelo menos 3–4 frases para cada descrição de ferramenta, mais se a ferramenta for complexa.
• Priorize as descrições, mas considere usar input_examples para ferramentas complexas. Descrições claras são o mais importante, mas para ferramentas com entradas complexas, objetos aninhados ou parâmetros sensíveis a formato, você pode usar o campo input_examples para fornecer exemplos validados pelo esquema. Consulte Fornecendo exemplos de uso de ferramentas para detalhes.
• Consolide operações relacionadas em menos ferramentas. Em vez de criar uma ferramenta separada para cada ação (create_pr, review_pr, merge_pr), agrupe-as em uma única ferramenta com um parâmetro action. Menos ferramentas, mais capazes, reduzem a ambiguidade de seleção e tornam sua superfície de ferramentas mais fácil para o Claude navegar.
• Use namespacing significativo nos nomes das ferramentas. Quando suas ferramentas abrangem vários serviços ou recursos, prefixe os nomes com o serviço (por exemplo, github_list_prs, slack_send_message). Isso torna a seleção de ferramentas inequívoca à medida que sua biblioteca cresce, e é especialmente importante ao usar a busca de ferramentas.
• Projete as respostas das ferramentas para retornar apenas informações de alto sinal. Retorne identificadores semânticos e estáveis (por exemplo, slugs ou UUIDs) em vez de referências internas opacas, e inclua apenas os campos de que o Claude precisa para raciocinar sobre seu próximo passo. Respostas inchadas desperdiçam contexto e tornam mais difícil para o Claude extrair o que importa.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

A boa descrição explica claramente o que a ferramenta faz, quando usá-la, quais dados ela retorna e o que o parâmetro ticker significa. A descrição ruim é muito breve e deixa o Claude com muitas perguntas em aberto sobre o comportamento e o uso da ferramenta.

Fornecendo exemplos de uso de ferramentas

Você pode fornecer exemplos concretos de entradas válidas de ferramentas para ajudar o Claude a entender como usar suas ferramentas de forma mais eficaz. Isso é particularmente útil para ferramentas complexas com objetos aninhados, parâmetros opcionais ou entradas sensíveis a formato.

Uso básico

Adicione um campo opcional input_examples à sua definição de ferramenta com um array de objetos de entrada de exemplo. Cada exemplo deve ser válido de acordo com o input_schema da ferramenta:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Os exemplos são incluídos no prompt junto com o esquema da sua ferramenta, mostrando ao Claude padrões concretos de chamadas de ferramentas bem formadas. Isso ajuda o Claude a entender quando incluir parâmetros opcionais, quais formatos usar e como estruturar entradas complexas.

Requisitos e limitações

• Validação de esquema - Cada exemplo deve ser válido de acordo com o input_schema da ferramenta. Exemplos inválidos retornam um erro 400
• Não suportado para ferramentas do lado do servidor ou conjuntos de ferramentas de cliente - Exemplos de entrada funcionam em ferramentas de cliente definidas pelo usuário e com esquema da Anthropic, exceto os conjuntos de ferramentas de uso de computador e uso de navegador, mas não em ferramentas de servidor como busca na web ou execução de código
• Custo de tokens - Os exemplos aumentam os tokens do prompt: ~20–50 tokens para exemplos simples, ~100–200 tokens para objetos aninhados complexos

Controlando a saída do Claude

Forçando o uso de ferramentas

Em alguns casos, você pode querer que o Claude use uma ferramenta específica para responder à pergunta do usuário, mesmo que o Claude, de outra forma, respondesse diretamente sem chamar uma ferramenta. Você pode fazer isso especificando a ferramenta no campo tool_choice da requisição.

Nem todo modelo e configuração suporta o uso forçado de ferramentas. Onde não é suportado, tool_choice: {"type": "any"} e tool_choice: {"type": "tool", "name": "..."} falham, enquanto tool_choice: {"type": "auto"} (o padrão) e tool_choice: {"type": "none"} continuam funcionando:

Em modelos que o suportam, as linhas destacadas são a única diferença em relação a uma requisição padrão de uso de ferramentas:

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Ao trabalhar com o parâmetro tool_choice, há quatro opções possíveis:

• auto permite que o Claude decida se deve chamar ou não qualquer uma das ferramentas fornecidas. Este é o valor padrão quando tools são fornecidas.
• any diz ao Claude que ele deve usar uma das ferramentas fornecidas, mas não força uma ferramenta específica.
• tool força o Claude a sempre usar uma ferramenta específica.
• none impede o Claude de usar qualquer ferramenta. Este é o valor padrão quando nenhuma tools é fornecida.

Este diagrama ilustra como cada opção funciona:

Observe que, quando você define tool_choice como any ou tool, a API preenche previamente a mensagem do assistente para forçar o uso de uma ferramenta. Isso significa que os modelos não emitirão uma resposta ou explicação em linguagem natural antes dos blocos de conteúdo tool_use, mesmo que explicitamente solicitados a fazê-lo.

Os testes mostraram que isso não deve reduzir o desempenho. Se você quiser que o modelo forneça contexto ou explicações em linguagem natural e ainda assim solicitar que o modelo use uma ferramenta específica, você pode usar {"type": "auto"} para tool_choice (o padrão) e adicionar instruções explícitas em uma mensagem user. Por exemplo: What's the weather like in London? Use the get_weather tool in your response.

Respostas do modelo com ferramentas

Ao usar ferramentas, o Claude frequentemente comenta o que está fazendo ou responde naturalmente ao usuário antes de chamar as ferramentas.

Por exemplo, dado o prompt "What's the weather like in San Francisco right now, and what time is it there?", o Claude pode responder com:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Esse estilo de resposta natural ajuda os usuários a entender o que o Claude está fazendo e cria uma interação mais conversacional. Você pode orientar o estilo e o conteúdo dessas respostas por meio dos seus prompts do sistema e fornecendo <examples> em seus prompts.

É importante observar que o Claude pode usar várias formulações e abordagens ao explicar suas ações. Seu código deve tratar essas respostas como qualquer outro texto gerado pelo assistente, e não depender de convenções de formatação específicas.

Próximos passos