---
title: Definir ferramentas
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools
description: Especifique esquemas de ferramentas, escreva descrições eficazes e controle quando Claude chama suas ferramentas.
---

## Pré-requisitos

* Familiaridade com a [visão geral do uso de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview)
* Uma chave de API do Claude e uma configuração funcional de SDK ou cURL

<Tip>
  Se estiver usando Claude com uso de ferramentas e pensamento, consulte [Pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) para mais informações.
</Tip>

## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference), para ver os campos que ela aceita. As ferramentas de uso de computador e uso de navegador são [conjuntos de ferramentas de cliente](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets): uma única entrada sem `name` que declara um conjunto fixo de ferramentas membro. Uma definição de ferramenta definida pelo usuário inclui:

| Parâmetro        | Descrição                                                                                                                                                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | O nome da ferramenta. Deve corresponder à regex `^[a-zA-Z0-9_-]{1,128}$`.                                                                                                                                                                                                   |
| `description`    | Uma descrição detalhada em texto simples do que a ferramenta faz, quando deve ser usada e como se comporta.                                                                                                                                                                 |
| `input_schema`   | Um objeto [JSON Schema](https://json-schema.org/) que define os parâmetros esperados para a ferramenta.                                                                                                                                                                     |
| `input_examples` | (Opcional) Um array de objetos de entrada de exemplo para ajudar Claude a entender como usar a ferramenta. Consulte [Fornecendo exemplos de uso de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools#providing-tool-use-examples). |

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#tool-definition-properties). 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets).

<Accordion title="Exemplo de definição de ferramenta simples">
  ```json JSON
  {
    "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"]
    }
  }
  ```

  Esta ferramenta, chamada `get_weather`, espera um objeto de entrada com uma string `location` obrigatória e uma string `unit` opcional que deve ser "celsius" ou "fahrenheit".
</Accordion>

### 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:

```text wrap
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 todos os detalhes 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 determinar 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool).

* **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.

* **Peça uma explicação, não um raciocínio.** Se um parâmetro pergunta ao Claude por que ele está fazendo a chamada, peça uma breve explicação ou as evidências de suporte. Um parâmetro que pede o pensamento do modelo ou um raciocínio passo a passo pode levar a uma recusa `reasoning_extraction`. Consulte [Mantenha o raciocínio nos blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).

<AccordionGroup>
  <Accordion title="Exemplo de uma boa descrição de ferramenta">
    ```json JSON
    {
      "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"]
      }
    }
    ```
  </Accordion>

  <Accordion title="Exemplo de descrição de ferramenta ruim">
    ```json JSON
    {
      "name": "get_stock_price",
      "description": "Gets the stock price for a ticker.",
      "input_schema": {
        "type": "object",
        "properties": {
          "ticker": {
            "type": "string"
          }
        },
        "required": ["ticker"]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

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.

<Tip>
  Para orientações mais aprofundadas sobre design de ferramentas (consolidação, nomenclatura e formatação de respostas), consulte [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents).
</Tip>

## 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:

<CodeGroup>
  ```bash cURL
  curl -sS https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "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"}
          ]
        }
      ],
      "messages": [
        {"role": "user", "content": "What is the weather like in San Francisco?"}
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  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?
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await 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"
            // Demonstra que 'unit' é opcional
          }
        ]
      }
    ],
    messages: [{ role: "user", content: "What's the weather like in San Francisco?" }]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Tools = [
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the current weather in a given location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }),
                      ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" }, description = "The unit of temperature" }),
                  },
                  Required = ["location"],
              },
              InputExamples =
              [
                  new Dictionary<string, JsonElement>()
                  {
                      { "location", JsonSerializer.SerializeToElement("San Francisco, CA") },
                      { "unit", JsonSerializer.SerializeToElement("fahrenheit") },
                  },
                  new Dictionary<string, JsonElement>()
                  {
                      { "location", JsonSerializer.SerializeToElement("Tokyo, Japan") },
                      { "unit", JsonSerializer.SerializeToElement("celsius") },
                  },
                  new Dictionary<string, JsonElement>()
                  {
                      { "location", JsonSerializer.SerializeToElement("New York, NY") },
                  },
              ],
          }),
      ],
      Messages = [
          new() { Role = Role.User, Content = "What's the weather like in San Francisco?" }
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Tools: []anthropic.ToolUnionParam{
  		{OfTool: &anthropic.ToolParam{
  			Name:        "get_weather",
  			Description: anthropic.String("Get the current weather in a given location"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{
  						"type":        "string",
  						"description": "The city and state, e.g. San Francisco, CA",
  					},
  					"unit": map[string]any{
  						"type":        "string",
  						"enum":        []string{"celsius", "fahrenheit"},
  						"description": "The unit of temperature",
  					},
  				},
  				Required: []string{"location"},
  			},
  			InputExamples: []map[string]any{
  				{
  					"location": "San Francisco, CA",
  					"unit":     "fahrenheit",
  				},
  				{
  					"location": "Tokyo, Japan",
  					"unit":     "celsius",
  				},
  				{
  					"location": "New York, NY",
  					// Demonstra que 'unit' é opcional
  				},
  			},
  		}},
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.Tool;
  import com.anthropic.models.messages.Tool.InputSchema;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the current weather in a given location")
              .inputSchema(InputSchema.builder()
                  .properties(JsonValue.from(Map.of(
                      "location", Map.of(
                          "type", "string",
                          "description", "The city and state, e.g. San Francisco, CA"
                      ),
                      "unit", Map.of(
                          "type", "string",
                          "enum", List.of("celsius", "fahrenheit"),
                          "description", "The unit of temperature"
                      )
                  )))
                  .required(List.of("location"))
                  .build())
              .putAdditionalProperty("input_examples", JsonValue.from(List.of(
                  Map.of(
                      "location", "San Francisco, CA",
                      "unit", "fahrenheit"
                  ),
                  Map.of(
                      "location", "Tokyo, Japan",
                      "unit", "celsius"
                  ),
                  Map.of(
                      "location", "New York, NY"
                  )
              )))
              .build())
          .addUserMessage("What's the weather like in San Francisco?")
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => "What's the weather like in San Francisco?"]
      ],
      model: 'claude-opus-5-5',
      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'
                  ]
              ]
          ]
      ],
  );
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = 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"
          }
        ]
      }
    ],
    messages: [
      { role: "user", content: "What's the weather like in San Francisco?" }
    ]
  )
  puts message
  ```
</CodeGroup>

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) e [uso de navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool), 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:

| Modelo ou configuração                                                                                                                                          | Restrição                                                                                                              | O que usar em vez disso                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ["Extended thinking" (pensamento estendido)](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking) manual (`thinking: {type: "enabled"}`) | `any` e `tool` não são suportados e resultam em erro                                                                   | `auto` ou `none`. O [pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) em si não bloqueia o uso forçado de ferramentas (modelos com pensamento ativado por padrão, como Claude Opus 5 e Claude Haiku 5.5, o aceitam, mas uma chamada forçada pula o pensamento: a resposta começa com a chamada de ferramenta e não tem bloco `thinking`); os modelos da próxima linha rejeitam o uso forçado de ferramentas independentemente das configurações de pensamento |
| Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e [Claude Mythos 5.1](https://platform.claude.com/docs/pt-BR/models/mythos-5-1/overview)                   | `any` e `tool` retornam um [erro 400](https://platform.claude.com/docs/pt-BR/api/errors#forced-tool-use-not-supported) | `auto` com [uso estrito de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use) para garantir entradas de ferramentas válidas segundo o esquema, ou [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) quando você precisar de uma resposta em um formato JSON fixo. O prompt ainda influencia qual ferramenta o `auto` escolhe. `none` também é suportado                                                   |

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:

<CodeGroup>
  ```bash cURL
  curl -sS https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-opus-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"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "tool_choice": {"type": "tool", "name": "get_weather"},
      "messages": [
        {"role": "user", "content": "What is the weather like in San Francisco?"}
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-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
        required: [location]
  tool_choice:
    type: tool
    name: get_weather
  messages:
    - role: user
      content: What's the weather like in San Francisco?
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-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"
            }
          },
          required: ["location"]
        }
      }
    ],
    tool_choice: { type: "tool", name: "get_weather" },
    messages: [{ role: "user", content: "What's the weather like in San Francisco?" }]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5,
      MaxTokens = 1024,
      Tools = [
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the current weather in a given location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }),
                  },
                  Required = ["location"],
              },
          }),
      ],
      ToolChoice = new ToolChoiceTool { Name = "get_weather" },
      Messages = [
          new() { Role = Role.User, Content = "What's the weather like in San Francisco?" }
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5,
  	MaxTokens: 1024,
  	Tools: []anthropic.ToolUnionParam{
  		{OfTool: &anthropic.ToolParam{
  			Name:        "get_weather",
  			Description: anthropic.String("Get the current weather in a given location"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{
  						"type":        "string",
  						"description": "The city and state, e.g. San Francisco, CA",
  					},
  				},
  				Required: []string{"location"},
  			},
  		}},
  	},
  	ToolChoice: anthropic.ToolChoiceUnionParam{OfTool: &anthropic.ToolChoiceToolParam{Name: "get_weather"}},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.Tool;
  import com.anthropic.models.messages.Tool.InputSchema;
  import com.anthropic.models.messages.ToolChoice;
  import com.anthropic.models.messages.ToolChoiceTool;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5)
          .maxTokens(1024L)
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the current weather in a given location")
              .inputSchema(InputSchema.builder()
                  .properties(JsonValue.from(Map.of(
                      "location", Map.of(
                          "type", "string",
                          "description", "The city and state, e.g. San Francisco, CA"
                      )
                  )))
                  .required(List.of("location"))
                  .build())
              .build())
          .toolChoice(ToolChoice.ofTool(ToolChoiceTool.builder()
              .name("get_weather")
              .build()))
          .addUserMessage("What's the weather like in San Francisco?")
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => "What's the weather like in San Francisco?"]
      ],
      model: 'claude-opus-5',
      toolChoice: ['type' => 'tool', 'name' => 'get_weather'],
      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']
              ]
          ]
      ],
  );
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: "claude-opus-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"
            }
          },
          required: ["location"]
        }
      }
    ],
    tool_choice: { type: "tool", name: "get_weather" },
    messages: [
      { role: "user", content: "What's the weather like in San Francisco?" }
    ]
  )
  puts message
  ```
</CodeGroup>

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

* `auto` permite que o Claude determine se deve chamar alguma das ferramentas fornecidas ou não. 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.

<Note>
  Ao usar o [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#what-invalidates-the-cache), alterações no parâmetro `tool_choice` invalidarão os blocos de mensagens em cache. As definições de ferramentas e os prompts do sistema permanecem em cache, mas o conteúdo das mensagens deve ser reprocessado.
</Note>

Este diagrama ilustra como cada opção funciona:

<Frame>
  ![Diagrama de três opções de tool\_choice: auto (uma ferramenta ou uma resposta simples), any (uma das ferramentas) e tool (a ferramenta nomeada)](https://platform.claude.com/docs/pt-BR/images/tool_choice.svg)
</Frame>

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.`

Forçar uma ferramenta também pula o pensamento em todos os modelos que aceitam o uso forçado de ferramentas: a resposta começa com o bloco `tool_use` e não tem bloco `thinking`. Para permitir que o modelo pense antes de chamar a ferramenta, use `auto` com uma instrução no prompt da mesma forma.

<Tip>
  **Chamadas de ferramentas garantidas com ferramentas estritas**

  Em modelos que suportam o uso forçado de ferramentas, combine `tool_choice: {"type": "any"}` com o [uso estrito de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use) para garantir tanto que uma de suas ferramentas seja chamada quanto que as entradas da ferramenta sigam estritamente seu esquema. Defina `strict: true` em suas definições de ferramentas para habilitar a validação de esquema.
</Tip>

### 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:

```json JSON
{
  "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

<CardGroup>
  <Card href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls" title="Lidar com chamadas de ferramentas">
    Analise blocos tool\_use e formate respostas tool\_result.
  </Card>

  <Card href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner" title="Tool Runner (SDK)">
    Deixe o SDK lidar com o loop agêntico automaticamente.
  </Card>

  <Card href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference" title="Referência de ferramentas">
    Diretório de ferramentas fornecidas pela Anthropic e propriedades opcionais.
  </Card>
</CardGroup>