---
title: Uso de ferramentas com Claude
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview
description: Conecte o Claude a ferramentas e APIs externas. Veja onde as ferramentas são executadas, quando o Claude as chama e qual ferramenta se adequa à sua tarefa.
---

O "tool use" (uso de ferramentas), também chamado de "function calling" (chamada de funções), permite que o Claude chame funções que você define ou que a Anthropic fornece. O Claude determina quando chamar uma ferramenta com base na solicitação do usuário e na descrição da ferramenta. Em seguida, ele retorna uma chamada estruturada que sua aplicação executa (ferramentas de cliente) ou que a Anthropic executa (ferramentas de servidor).

Aqui está um exemplo mínimo usando uma ferramenta de servidor, a [ferramenta de busca na web](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool), que a Anthropic executa para você:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "tools": [{"type": "web_search_20260209", "name": "web_search"}],
      "messages": [{"role": "user", "content": "What'\''s the latest on the Mars rover?"}]
    }'
  ```

  ```bash CLI
  ant messages create --transform content --format yaml \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --tool '{type: web_search_20260209, name: web_search}' \
    --message '{role: user, content: "What is the latest on the Mars rover?"}'
  ```

  ```python Python
  client = anthropic.Anthropic()
  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      tools=[{"type": "web_search_20260209", "name": "web_search"}],
      messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
  )
  print(response.content)
  ```

  ```typescript TypeScript
  const client = new Anthropic();
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools: [{ type: "web_search_20260209", name: "web_search" }],
    messages: [{ role: "user", content: "What's the latest on the Mars rover?" }]
  });
  console.log(response.content);
  ```

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

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Tools = [new ToolUnion(new WebSearchTool20260209())],
      Messages = [new() { Role = Role.User, Content = "What's the latest on the Mars rover?" }]
  };

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

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

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Tools: []anthropic.ToolUnionParam{
  		{OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the latest on the Mars rover?")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.Content)
  ```

  ```java Java
  import com.anthropic.models.messages.WebSearchTool20260209;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addTool(WebSearchTool20260209.builder().build())
          .addUserMessage("What's the latest on the Mars rover?")
          .build();

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

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

  $message = $client->messages->create(
      model: 'claude-opus-5-5',
      maxTokens: 1024,
      tools: [
          ['type' => 'web_search_20260209', 'name' => 'web_search'],
      ],
      messages: [
          ['role' => 'user', 'content' => "What's the latest on the Mars rover?"],
      ],
  );

  echo $message;
  ```

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

  message = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools: [{ type: "web_search_20260209", name: "web_search" }],
    messages: [{ role: "user", content: "What's the latest on the Mars rover?" }]
  )
  puts message.content
  ```
</CodeGroup>

O Claude executa a busca na infraestrutura da Anthropic e retorna os resultados citados na mesma resposta. Para que o Claude chame uma função que você define, passe uma ferramenta com um `input_schema` e, em seguida, execute a chamada quando o Claude retornar um bloco `tool_use`. [Como funciona o uso de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview#how-tool-use-works) mostra esse ciclo completo de ponta a ponta. Saiba mais sobre [como definir ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools) e [como lidar com chamadas de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls).

## Como funciona o uso de ferramentas

As ferramentas diferem principalmente pelo local onde o código é executado. As **ferramentas de cliente** (incluindo ferramentas definidas pelo usuário e ferramentas com esquemas definidos pela Anthropic, como `bash` e `text_editor`) são executadas na sua aplicação. O Claude responde com `stop_reason: "tool_use"` e um ou mais blocos `tool_use`. Seu código executa a operação e envia de volta um `tool_result`. As **ferramentas de servidor** (como `web_search`, `web_fetch`, `code_execution` e `tool_search`) são executadas na infraestrutura da Anthropic: você vê os resultados diretamente sem lidar com a execução, a menos que o Claude chame a ferramenta no mesmo grupo de chamadas de ferramentas paralelas que uma das suas ferramentas de cliente (consulte [Motivos de parada e fallback](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#tool-use)).

Aqui está esse ciclo completo para uma ferramenta de cliente. A primeira requisição define uma ferramenta `get_weather`, e o Claude responde à pergunta chamando-a: a resposta traz um bloco `tool_use`, seu código executa a consulta e uma segunda requisição envia o resultado de volta em um bloco `tool_result` para que o Claude possa responder com a resposta.

<CodeGroup>
  ```bash cURL
  # Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
  TOOLS='[
    {
      "name": "get_weather",
      "description": "Get the current weather for a given location.",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "City and state, e.g. San Francisco, CA"}
        },
        "required": ["location"]
      }
    }
  ]'
  USER_MSG="What's the weather in San Francisco?"
  RESPONSE=$(curl -s https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d "$(jq -n --argjson tools "$TOOLS" --arg msg "$USER_MSG" '{
      model: "claude-opus-5-5",
      max_tokens: 1024,
      tools: $tools,
      # Solicite no máximo uma chamada de ferramenta por turno.
      tool_choice: {type: "auto", disable_parallel_tool_use: true},
      messages: [{role: "user", content: $msg}]
    }')")
  TOOL_USE=$(echo "$RESPONSE" | jq '.content[] | select(.type == "tool_use")')
  echo "Claude called $(echo "$TOOL_USE" | jq -r '.name') with $(echo "$TOOL_USE" | jq -c '.input')"

  # Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
  # Claude usa o resultado para responder à pergunta original.
  WEATHER="15 degrees Celsius, partly cloudy"
  curl -s https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d "$(jq -n \
      --argjson tools "$TOOLS" \
      --arg msg "$USER_MSG" \
      --argjson assistant "$(echo "$RESPONSE" | jq '.content')" \
      --arg tool_use_id "$(echo "$TOOL_USE" | jq -r '.id')" \
      --arg weather "$WEATHER" \
      '{
        model: "claude-opus-5-5",
        max_tokens: 1024,
        tools: $tools,
        tool_choice: {type: "auto", disable_parallel_tool_use: true},
        messages: [
          {role: "user", content: $msg},
          {role: "assistant", content: $assistant},
          {role: "user", content: [
            {type: "tool_result", tool_use_id: $tool_use_id, content: $weather}
          ]}
        ]
      }')"
  ```

  ```bash CLI
  # ant lê o corpo da requisição como YAML via stdin; jq leva o estado da conversa
  # para a segunda requisição.
  USER_MSG="What's the weather in San Francisco?"
  MESSAGES=$(jq -n --arg msg "$USER_MSG" '[{role: "user", content: $msg}]')
  call_api() {
    {
      cat <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  # Peça no máximo uma chamada de ferramenta por turno.
  tool_choice: {type: auto, disable_parallel_tool_use: true}
  tools:
    - name: get_weather
      description: Get the current weather for a given location.
      input_schema:
        type: object
        properties:
          location: {type: string, description: "City and state, e.g. San Francisco, CA"}
        required: [location]
  YAML
      printf 'messages: %s\n' "$MESSAGES"
    } | ant messages create --format json
  }

  # Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
  RESPONSE=$(call_api)
  TOOL_USE=$(jq '.content[] | select(.type == "tool_use")' <<<"$RESPONSE")
  echo "Claude called $(jq -r '.name' <<<"$TOOL_USE") with $(jq -c '.input' <<<"$TOOL_USE")"

  # Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
  WEATHER="15 degrees Celsius, partly cloudy"
  MESSAGES=$(jq \
    --argjson assistant "$(jq '.content' <<<"$RESPONSE")" \
    --arg tool_use_id "$(jq -r '.id' <<<"$TOOL_USE")" \
    --arg weather "$WEATHER" \
    '. + [
      {role: "assistant", content: $assistant},
      {role: "user", content: [
        {type: "tool_result", tool_use_id: $tool_use_id, content: $weather}
      ]}
    ]' <<<"$MESSAGES")

  # Claude usa o resultado para responder à pergunta original.
  call_api
  ```

  ```python Python
  client = anthropic.Anthropic()

  tools = [
      {
          "name": "get_weather",
          "description": "Get the current weather for a given location.",
          "input_schema": {
              "type": "object",
              "properties": {
                  "location": {
                      "type": "string",
                      "description": "City and state, e.g. San Francisco, CA",
                  }
              },
              "required": ["location"],
          },
      }
  ]
  messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

  # Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      tools=tools,
      # Solicite no máximo uma chamada de ferramenta por turno.
      tool_choice={"type": "auto", "disable_parallel_tool_use": True},
      messages=messages,
  )
  tool_use = next(block for block in response.content if block.type == "tool_use")
  print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

  # Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
  weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
  messages += [
      {"role": "assistant", "content": response.content},
      {
          "role": "user",
          "content": [
              {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
          ],
      },
  ]
  followup = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      tools=tools,
      tool_choice={"type": "auto", "disable_parallel_tool_use": True},
      messages=messages,
  )

  # Claude usa o resultado para responder à pergunta original.
  final_text = next(block for block in followup.content if block.type == "text")
  print(final_text.text)
  ```

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

  const tools: Anthropic.Tool[] = [
    {
      name: "get_weather",
      description: "Get the current weather for a given location.",
      input_schema: {
        type: "object",
        properties: {
          location: { type: "string", description: "City and state, e.g. San Francisco, CA" }
        },
        required: ["location"]
      }
    }
  ];
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: "What's the weather in San Francisco?" }
  ];

  // Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools,
    // Solicite no máximo uma chamada de ferramenta por turno.
    tool_choice: { type: "auto", disable_parallel_tool_use: true },
    messages
  });
  const toolUse = response.content.find(
    (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
  )!;
  console.log(`Claude called ${toolUse.name} with ${JSON.stringify(toolUse.input)}`);

  // Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
  const weather = "15 degrees Celsius, partly cloudy"; // your weather lookup goes here
  messages.push(
    { role: "assistant", content: response.content },
    {
      role: "user",
      content: [{ type: "tool_result", tool_use_id: toolUse.id, content: weather }]
    }
  );
  const followup = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools,
    tool_choice: { type: "auto", disable_parallel_tool_use: true },
    messages
  });

  // Claude usa o resultado para responder à pergunta original.
  const finalText = followup.content.find(
    (block): block is Anthropic.TextBlock => block.type === "text"
  )!;
  console.log(finalText.text);
  ```

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

  List<ToolUnion> tools =
  [
      new ToolUnion(new Tool()
      {
          Name = "get_weather",
          Description = "Get the current weather for a given location.",
          InputSchema = new InputSchema()
          {
              Properties = new Dictionary<string, JsonElement>
              {
                  ["location"] = JsonSerializer.SerializeToElement(new
                  {
                      type = "string",
                      description = "City and state, e.g. San Francisco, CA",
                  }),
              },
              Required = ["location"],
          },
      }),
  ];

  // Solicite no máximo uma chamada de ferramenta por turno.
  var toolChoice = new ToolChoice(new ToolChoiceAuto { DisableParallelToolUse = true });

  const string userPrompt = "What's the weather in San Francisco?";

  // Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Tools = tools,
      ToolChoice = toolChoice,
      Messages = [new() { Role = Role.User, Content = userPrompt }],
  });
  ToolUseBlock? toolUse = null;
  foreach (var block in response.Content)
  {
      if (block.TryPickToolUse(out var picked))
      {
          toolUse = picked;
          break;
      }
  }
  Console.WriteLine($"Claude called {toolUse!.Name} with {JsonSerializer.Serialize(toolUse.Input)}");

  // Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
  var weather = "15 degrees Celsius, partly cloudy";
  List<ContentBlockParam> toolResults =
  [
      new ContentBlockParam(new ToolResultBlockParam()
      {
          ToolUseID = toolUse.ID,
          Content = weather,
      }),
  ];
  var followup = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Tools = tools,
      ToolChoice = toolChoice,
      Messages =
      [
          new() { Role = Role.User, Content = userPrompt },
          new() { Role = Role.Assistant, Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList() },
          new() { Role = Role.User, Content = new MessageParamContent(toolResults) },
      ],
  });

  // Claude usa o resultado para responder à pergunta original.
  foreach (var block in followup.Content)
  {
      if (block.TryPickText(out var text))
      {
          Console.WriteLine(text.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()
  ctx := context.Background()

  tools := []anthropic.ToolUnionParam{
  	{OfTool: &anthropic.ToolParam{
  		Name:        "get_weather",
  		Description: anthropic.String("Get the current weather for a given location."),
  		InputSchema: anthropic.ToolInputSchemaParam{
  			Properties: map[string]any{
  				"location": map[string]any{
  					"type":        "string",
  					"description": "City and state, e.g. San Francisco, CA",
  				},
  			},
  			Required: []string{"location"},
  		},
  	}},
  }
  // Solicite no máximo uma chamada de ferramenta por turno.
  toolChoice := anthropic.ToolChoiceUnionParam{
  	OfAuto: &anthropic.ToolChoiceAutoParam{DisableParallelToolUse: anthropic.Bool(true)},
  }
  messages := []anthropic.MessageParam{
  	anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in San Francisco?")),
  }

  // Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
  response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  	Model:      anthropic.ModelClaudeOpus5_5,
  	MaxTokens:  1024,
  	Tools:      tools,
  	ToolChoice: toolChoice,
  	Messages:   messages,
  })
  if err != nil {
  	log.Fatal(err)
  }
  var toolUse anthropic.ContentBlockUnion
  for _, block := range response.Content {
  	if block.Type == "tool_use" {
  		toolUse = block
  		break
  	}
  }
  fmt.Printf("Claude called %s with %s\n", toolUse.Name, string(toolUse.Input))

  // Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
  weather := "15 degrees Celsius, partly cloudy"
  var assistantContent []anthropic.ContentBlockParamUnion
  for _, block := range response.Content {
  	assistantContent = append(assistantContent, block.ToParam())
  }
  messages = append(messages,
  	anthropic.NewAssistantMessage(assistantContent...),
  	anthropic.NewUserMessage(anthropic.NewToolResultBlock(toolUse.ID, weather, false)),
  )
  followup, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  	Model:      anthropic.ModelClaudeOpus5_5,
  	MaxTokens:  1024,
  	Tools:      tools,
  	ToolChoice: toolChoice,
  	Messages:   messages,
  })
  if err != nil {
  	log.Fatal(err)
  }

  // Claude usa o resultado para responder à pergunta original.
  for _, block := range followup.Content {
  	if block.Type == "text" {
  		fmt.Println(block.Text)
  	}
  }
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.messages.ContentBlockParam;
  // ...
  import com.anthropic.models.messages.Tool;
  import com.anthropic.models.messages.Tool.InputSchema;
  import com.anthropic.models.messages.ToolChoiceAuto;
  import com.anthropic.models.messages.ToolResultBlockParam;
  import com.anthropic.models.messages.ToolUseBlock;
  // ...

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      Tool weatherTool = Tool.builder()
          .name("get_weather")
          .description("Get the current weather for a given location.")
          .inputSchema(InputSchema.builder()
              .properties(JsonValue.from(Map.of(
                  "location", Map.of(
                      "type", "string",
                      "description", "City and state, e.g. San Francisco, CA"
                  )
              )))
              .required(List.of("location"))
              .build())
          .build();

      // Solicite no máximo uma chamada de ferramenta por turno.
      ToolChoiceAuto toolChoice = ToolChoiceAuto.builder()
          .disableParallelToolUse(true)
          .build();

      String userPrompt = "What's the weather in San Francisco?";

      // Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
      Message response = client.messages().create(MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addTool(weatherTool)
          .toolChoice(toolChoice)
          .addUserMessage(userPrompt)
          .build());
      ToolUseBlock toolUse = response.content().stream()
          .flatMap(block -> block.toolUse().stream())
          .findFirst()
          .orElseThrow();
      IO.println("Claude called " + toolUse.name() + " with " + toolUse._input());

      // Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
      String weather = "15 degrees Celsius, partly cloudy";
      Message followup = client.messages().create(MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addTool(weatherTool)
          .toolChoice(toolChoice)
          .addUserMessage(userPrompt)
          .addMessage(response)
          .addUserMessageOfBlockParams(List.of(ContentBlockParam.ofToolResult(
              ToolResultBlockParam.builder()
                  .toolUseId(toolUse.id())
                  .content(weather)
                  .build())))
          .build());

      // Claude usa o resultado para responder à pergunta original.
      followup.content().stream()
          .flatMap(block -> block.text().stream())
          .forEach(textBlock -> IO.println(textBlock.text()));
  }
  ```

  ```php PHP
  use Anthropic\Messages\ToolChoiceAuto;

  $client = new Client();

  $tools = [
      [
          'name' => 'get_weather',
          'description' => 'Get the current weather for a given location.',
          'input_schema' => [
              'type' => 'object',
              'properties' => [
                  'location' => [
                      'type' => 'string',
                      'description' => 'City and state, e.g. San Francisco, CA',
                  ],
              ],
              'required' => ['location'],
          ],
      ],
  ];
  $userMessage = ['role' => 'user', 'content' => "What's the weather in San Francisco?"];

  // Solicite no máximo uma chamada de ferramenta por turno.
  $toolChoice = ToolChoiceAuto::with(disableParallelToolUse: true);

  // Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
  $response = $client->messages->create(
      model: 'claude-opus-5-5',
      maxTokens: 1024,
      tools: $tools,
      toolChoice: $toolChoice,
      messages: [$userMessage],
  );
  $toolUse = null;
  foreach ($response->content as $block) {
      if ($block->type === 'tool_use') {
          $toolUse = $block;
          break;
      }
  }
  printf("Claude called %s with %s\n", $toolUse->name, json_encode($toolUse->input));

  // Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
  $weather = '15 degrees Celsius, partly cloudy';
  $followup = $client->messages->create(
      model: 'claude-opus-5-5',
      maxTokens: 1024,
      tools: $tools,
      toolChoice: $toolChoice,
      messages: [
          $userMessage,
          ['role' => 'assistant', 'content' => $response->content],
          [
              'role' => 'user',
              'content' => [
                  [
                      'type' => 'tool_result',
                      'tool_use_id' => $toolUse->id,
                      'content' => $weather,
                  ],
              ],
          ],
      ],
  );

  // Claude usa o resultado para responder à pergunta original.
  foreach ($followup->content as $block) {
      if ($block->type === 'text') {
          echo $block->text, "\n";
      }
  }
  ```

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

  tools = [
    {
      name: "get_weather",
      description: "Get the current weather for a given location.",
      input_schema: {
        type: "object",
        properties: {
          location: {type: "string", description: "City and state, e.g. San Francisco, CA"}
        },
        required: ["location"]
      }
    }
  ]
  messages = [{role: "user", content: "What's the weather in San Francisco?"}]

  # Claude responde com um bloco tool_use indicando a ferramenta e seus argumentos.
  response = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools: tools,
    # Solicite no máximo uma chamada de ferramenta por turno.
    tool_choice: {type: "auto", disable_parallel_tool_use: true},
    messages: messages
  )
  tool_use = response.content.find { |block| block.type == :tool_use }
  puts "Claude called #{tool_use.name} with #{JSON.generate(tool_use.input)}"

  # Execute a ferramenta e envie o resultado de volta em um bloco tool_result.
  weather = "15 degrees Celsius, partly cloudy"
  messages += [
    {role: "assistant", content: response.content},
    {
      role: "user",
      content: [
        {type: "tool_result", tool_use_id: tool_use.id, content: weather}
      ]
    }
  ]
  followup = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools: tools,
    tool_choice: {type: "auto", disable_parallel_tool_use: true},
    messages: messages
  )

  # Claude usa o resultado para responder à pergunta original.
  final_text = followup.content.find { |block| block.type == :text }
  puts final_text.text
  ```
</CodeGroup>

```text Output wrap
Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.
```

[Lidar com chamadas de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls) aborda cada etapa em detalhes, incluindo a formatação de resultados e a sinalização de erros; [Uso de ferramentas em paralelo](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use) aborda respostas que chamam várias ferramentas de uma só vez. Para não precisar escrever esse ciclo você mesmo, use o [Tool Runner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner): o SDK executa suas ferramentas e envia os resultados de volta automaticamente.

Para o modelo conceitual completo, incluindo o loop agêntico e quando escolher cada abordagem, consulte [Como funciona o uso de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/how-tool-use-works).

Para se conectar a servidores do Model Context Protocol (MCP), consulte o [conector MCP](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector). Para criar seu próprio cliente MCP, consulte o guia do Model Context Protocol sobre [como criar um cliente MCP](https://modelcontextprotocol.io/docs/develop/build-client).

## Quando o Claude usa ferramentas

Com o `tool_choice` padrão de `{"type": "auto"}`, o Claude determina a cada turno se deve chamar uma ferramenta ou responder diretamente. Ele chama uma ferramenta quando a solicitação corresponde à capacidade descrita daquela ferramenta e a resposta ainda não está no contexto. Ele responde diretamente para conhecimento estável, tarefas criativas e turnos conversacionais.

Esse limite pode ser ajustado por meio do seu prompt do sistema. Se o Claude não estiver chamando ferramentas quando você espera, uma instrução leve como `"Use the tools to investigate before responding."` aumenta o uso de ferramentas. Uma forma mais forte, como `"Always call a tool first before responding."`, vai mais longe. Por outro lado, `"Use your judgment about whether to call a tool or respond directly."` mantém o comportamento de acionamento conservador.

Para exigir uma chamada de ferramenta em vez de depender de prompts, defina [`tool_choice`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools#forcing-tool-use).

<Tip>
  **Garanta a conformidade com o esquema usando o uso estrito de ferramentas**

  Adicione `strict: true` às definições das suas ferramentas personalizadas para garantir que as chamadas de ferramentas do Claude sempre correspondam exatamente ao seu esquema. Consulte [Uso estrito de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use).
</Tip>

A página de cada ferramenta de servidor descreve seu próprio limite de acionamento em mais detalhes.

<Accordion title="Quando parâmetros obrigatórios estão ausentes">
  Se o prompt do usuário não incluir informações suficientes para preencher todos os parâmetros obrigatórios de uma ferramenta, o Claude Opus tem muito mais probabilidade de reconhecer que um parâmetro está ausente e solicitá-lo. O Claude Sonnet pode perguntar, especialmente quando instruído a pensar antes de emitir uma solicitação de ferramenta. Mas ele também pode inferir um valor razoável.

  Por exemplo, dada uma ferramenta `get_weather` que exige um parâmetro `location`, se você perguntar ao Claude "Como está o tempo?" sem especificar um local, o Claude (particularmente o Claude Sonnet) pode adivinhar valores que você não forneceu:

  ```json JSON
  {
    "type": "tool_use",
    "id": "toolu_01A09q90qw90lq917835lq9",
    "name": "get_weather",
    "input": { "location": "New York, NY", "unit": "fahrenheit" }
  }
  ```

  Esse comportamento não é garantido, especialmente para prompts mais ambíguos e para modelos menos capazes.
</Accordion>

## Escolha uma ferramenta

Para strings de `type`, versões e cabeçalhos beta, consulte a [Referência de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference).

### Suas próprias ferramentas

Para ferramentas que você define, você escreve o esquema e sua aplicação executa cada chamada.

<CardGroup cols={2}>
  <Card title="Definir ferramentas" icon="hammer" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools">
    Especifique esquemas de ferramentas, escreva descrições e controle quando o Claude chama suas ferramentas.
  </Card>

  <Card title="Lidar com chamadas de ferramentas" icon="arrows-left-right" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls">
    Analise blocos `tool_use`, formate respostas `tool_result` e lide com erros.
  </Card>
</CardGroup>

### Ferramentas de cliente com esquema da Anthropic

A Anthropic publica o esquema e treina o Claude nele. Sua aplicação ainda executa cada chamada e retorna o `tool_result`.

<CardGroup cols={2}>
  <Card title="Ferramenta de memória" icon="brain" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool">
    Armazene e recupere informações entre conversas em arquivos que você controla.
  </Card>

  <Card title="Ferramenta Bash" icon="terminal" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/bash-tool">
    Execute comandos de shell em uma sessão persistente que mantém o estado.
  </Card>

  <Card title="Ferramenta de editor de texto" icon="edit" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool">
    Visualize e modifique arquivos de texto para depurar, corrigir e melhorar código.
  </Card>

  <Card title="Ferramenta de uso do computador" icon="computer" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool">
    Faça capturas de tela e controle o mouse e o teclado em um ambiente de desktop.
  </Card>

  <Card title="Ferramenta de uso do navegador" icon="browser" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool">
    Navegue, leia e interaja com páginas da web no seu próprio ambiente de navegador.
  </Card>
</CardGroup>

### Ferramentas de servidor

As ferramentas de servidor são executadas na infraestrutura da Anthropic, sem código de tratamento na sua aplicação. Consulte [Ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) para conhecer a mecânica que elas compartilham.

<CardGroup cols={2}>
  <Card title="Ferramenta de busca na web" icon="magnifying-glass" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool">
    Pesquise na web informações além da data de corte de conhecimento, com fontes citadas.
  </Card>

  <Card title="Ferramenta de busca de conteúdo web" icon="download" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-fetch-tool">
    Recupere o conteúdo completo de páginas da web e documentos PDF especificados.
  </Card>

  <Card title="Ferramenta de execução de código" icon="code" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool">
    Execute código Python e bash em um contêiner isolado para analisar dados e gerar arquivos.
  </Card>

  <Card title="Ferramenta de consultor" icon="lightbulb" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool">
    Permita que um modelo executor mais rápido consulte um modelo consultor de maior inteligência durante a geração.
  </Card>

  <Card title="Ferramenta de busca de ferramentas" icon="library" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool">
    Trabalhe com milhares de ferramentas descobrindo-as e carregando-as sob demanda.
  </Card>

  <Card title="Conector MCP" icon="link" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector">
    Conecte-se a servidores MCP remotos a partir da Messages API sem um cliente MCP separado.
  </Card>
</CardGroup>

<Note>
  O [Claude Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview) fornece um conjunto de ferramentas integrado que o Claude usa de forma autônoma dentro de uma sessão. Para esse conjunto de ferramentas e a forma do Managed Agents de adicionar ferramentas personalizadas, consulte sua página de [Ferramentas](https://platform.claude.com/docs/pt-BR/managed-agents/tools).
</Note>

## Preços

As solicitações de "tool use" (uso de ferramentas) são precificadas com base em:

1. O número total de tokens de entrada enviados ao modelo (incluindo no parâmetro `tools`)
2. O número de tokens de saída gerados
3. Para ferramentas do lado do servidor, precificação adicional baseada no uso (por exemplo, a pesquisa na web cobra por pesquisa realizada)

As ferramentas do lado do cliente são precificadas da mesma forma que qualquer outra solicitação da Claude API, embora as ferramentas do lado do servidor possam incorrer em cobranças adicionais com base em seu uso específico.

Os tokens adicionais do uso de ferramentas vêm de:

* O parâmetro `tools` nas solicitações de API (nomes, descrições e esquemas das ferramentas)
* Blocos de conteúdo `tool_use` nas solicitações e respostas de API
* Blocos de conteúdo `tool_result` nas solicitações de API

Quando você usa `tools`, a API também inclui automaticamente um "system prompt" (prompt do sistema) especial para o modelo que habilita o uso de ferramentas. O número de tokens de uso de ferramentas necessários para cada modelo está listado na tabela a seguir (excluindo os tokens adicionais listados anteriormente). Observe que a tabela pressupõe que pelo menos 1 ferramenta seja fornecida. Se nenhuma `tools` for fornecida, então uma escolha de ferramenta `none` usa 0 tokens adicionais de prompt do sistema.

| Model                                                                                                                                   | Tool use system prompt tokens: auto, none | Tool use system prompt tokens: any, tool |
| :-------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------- | :--------------------------------------- |
| Claude Opus 5.5                                                                                                                         | 286 tokens                                |                                          |
| Claude Opus 5                                                                                                                           | 286 tokens                                | 406 tokens                               |
| Claude Opus 4.8                                                                                                                         | 290 tokens                                | 410 tokens                               |
| Claude Opus 4.7                                                                                                                         | 675 tokens                                | 804 tokens                               |
| Claude Opus 4.6                                                                                                                         | 497 tokens                                | 589 tokens                               |
| Claude Opus 4.5                                                                                                                         | 496 tokens                                | 588 tokens                               |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | 313 tokens                                | 315 tokens                               |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations))               | 313 tokens                                | 315 tokens                               |
| Claude Sonnet 5.5                                                                                                                       | 286 tokens                                |                                          |
| Claude Sonnet 5                                                                                                                         | 354 tokens                                | 474 tokens                               |
| Claude Sonnet 4.6                                                                                                                       | 497 tokens                                | 589 tokens                               |
| Claude Sonnet 4.5                                                                                                                       | 496 tokens                                | 588 tokens                               |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | 313 tokens                                | 315 tokens                               |
| Claude Haiku 5.5                                                                                                                        | 286 tokens                                | 406 tokens                               |
| Claude Haiku 4.5                                                                                                                        | 496 tokens                                | 588 tokens                               |
| Claude Haiku 3.5 ([retired, except on Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations))            | 264 tokens                                | 355 tokens                               |

* **auto, none:** The count when tool\_choice is auto or none.
* **any, tool:** The count when tool\_choice is any or tool.
* **Retired:** May still be available on other cloud platforms. See [Model deprecations](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations) for more.

Essas contagens de tokens são adicionadas aos seus tokens normais de entrada e saída para calcular o custo total de uma solicitação.

Consulte a tabela de [Visão geral dos modelos](https://platform.claude.com/docs/pt-BR/models/overview#latest-models-comparison) para os preços atuais por modelo.

Quando você envia um prompt de uso de ferramentas, assim como qualquer outra requisição de API, a resposta inclui as contagens de tokens de entrada e de saída nas métricas de `usage` relatadas.

Algumas ferramentas de servidor adicionam cobranças baseadas em uso além dos tokens: consulte a [Ferramenta de busca na web](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#usage-and-pricing) e a [Ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#usage-and-pricing) para conhecer suas tarifas.

## Próximos passos

<CardGroup cols={3}>
  <Card href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/how-tool-use-works" title="Como funciona o uso de ferramentas" icon="compass">
    Entenda o loop de uso de ferramentas, onde as ferramentas são executadas e quando usar ferramentas em vez de prosa.
  </Card>

  <Card href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/build-a-tool-using-agent" title="Tutorial: Crie um agente que usa ferramentas" icon="graduation-cap">
    Um passo a passo guiado, de uma única chamada de ferramenta até um loop agêntico pronto para produção.
  </Card>

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