---
title: Definir herramientas
url: https://platform.claude.com/docs/es/agents-and-tools/tool-use/define-tools
description: Especifica esquemas de herramientas, escribe descripciones efectivas y controla cuándo Claude llama a tus herramientas.
---

## Requisitos previos

* Familiaridad con la [descripción general del uso de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/overview)
* Una clave de API de Claude y una configuración funcional del SDK o de cURL

<Tip>
  Si usas Claude con uso de herramientas y pensamiento, consulta [Pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking) para obtener más información.
</Tip>

## Especificar herramientas de cliente

Las herramientas de cliente se especifican en el parámetro de nivel superior `tools` de la solicitud a la API. Las herramientas de cliente con esquema de Anthropic, como las herramientas bash y de editor de texto, se declaran mediante un `type` versionado por fecha; consulta la página de cada herramienta, enlazada desde la [Referencia de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference), para ver los campos que acepta. Las herramientas de uso de computadora y uso de navegador son [conjuntos de herramientas de cliente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets): una única entrada sin `name` que declara un conjunto fijo de herramientas miembro. Una definición de herramienta definida por el usuario incluye:

| Parámetro        | Descripción                                                                                                                                                                                                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | El nombre de la herramienta. Debe coincidir con la expresión regular `^[a-zA-Z0-9_-]{1,128}$`.                                                                                                                                                                                    |
| `description`    | Una descripción detallada en texto plano de lo que hace la herramienta, cuándo debe usarse y cómo se comporta.                                                                                                                                                                    |
| `input_schema`   | Un objeto [JSON Schema](https://json-schema.org/) que define los parámetros esperados para la herramienta.                                                                                                                                                                        |
| `input_examples` | (Opcional) Un arreglo de objetos de entrada de ejemplo para ayudar a Claude a entender cómo usar la herramienta. Consulta [Proporcionar ejemplos de uso de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/define-tools#providing-tool-use-examples). |

Para ver el conjunto completo de propiedades opcionales disponibles en cualquier definición de herramienta individual, incluidas `cache_control`, `strict`, `defer_loading` y `allowed_callers`, consulta la [Referencia de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#tool-definition-properties). Una entrada de conjunto de herramientas de cliente acepta `cache_control` y `allowed_callers` en la entrada y establece `defer_loading` por miembro; consulta [Conjuntos de herramientas de cliente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets).

<Accordion title="Ejemplo de definición de herramienta simple">
  ```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 herramienta, llamada `get_weather`, espera un objeto de entrada con una cadena `location` obligatoria y una cadena `unit` opcional que debe ser "celsius" o "fahrenheit".
</Accordion>

### Indicación del sistema para el uso de herramientas

Cuando llamas a la API de Claude con el parámetro `tools`, la API construye una "system prompt" (indicación del sistema) especial a partir de las definiciones de herramientas, la configuración de herramientas y cualquier indicación del sistema especificada por el usuario. La indicación construida está diseñada para instruir al modelo a usar las herramientas especificadas y proporcionar el contexto necesario para que la herramienta funcione correctamente:

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

### Mejores prácticas para las definiciones de herramientas

Para obtener el mejor rendimiento de Claude al usar herramientas, sigue estas pautas:

* **Proporciona descripciones extremadamente detalladas.** Este es, con diferencia, el factor más importante en el rendimiento de las herramientas. Tus descripciones deben explicar cada detalle sobre la herramienta, incluyendo:

  * Qué hace la herramienta
  * Cuándo debe usarse (y cuándo no)
  * Qué significa cada parámetro y cómo afecta el comportamiento de la herramienta
  * Cualquier advertencia o limitación importante, como qué información no devuelve la herramienta si el nombre de la herramienta no es claro. Cuanto más contexto puedas darle a Claude sobre tus herramientas, mejor será para determinar cuándo y cómo usarlas. Apunta a al menos 3–4 oraciones por cada descripción de herramienta, más si la herramienta es compleja.

* **Prioriza las descripciones, pero considera usar `input_examples` para herramientas complejas.** Las descripciones claras son lo más importante, pero para herramientas con entradas complejas, objetos anidados o parámetros sensibles al formato, puedes usar el campo `input_examples` para proporcionar ejemplos validados contra el esquema. Consulta [Proporcionar ejemplos de uso de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) para más detalles.

* **Consolida operaciones relacionadas en menos herramientas.** En lugar de crear una herramienta separada para cada acción (`create_pr`, `review_pr`, `merge_pr`), agrúpalas en una sola herramienta con un parámetro `action`. Menos herramientas, pero más capaces, reducen la ambigüedad en la selección y hacen que tu superficie de herramientas sea más fácil de navegar para Claude.

* **Usa espacios de nombres significativos en los nombres de las herramientas.** Cuando tus herramientas abarcan múltiples servicios o recursos, antepón a los nombres el servicio (por ejemplo, `github_list_prs`, `slack_send_message`). Esto hace que la selección de herramientas no sea ambigua a medida que tu biblioteca crece, y es especialmente importante al usar la [búsqueda de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool).

* **Diseña las respuestas de las herramientas para que devuelvan solo información de alta señal.** Devuelve identificadores semánticos y estables (por ejemplo, slugs o UUIDs) en lugar de referencias internas opacas, e incluye solo los campos que Claude necesita para razonar sobre su siguiente paso. Las respuestas infladas desperdician contexto y dificultan que Claude extraiga lo que importa.

* **Pide una explicación, no un razonamiento.** Si un parámetro le pregunta a Claude por qué está haciendo la llamada, pide una explicación breve o la evidencia que la respalda. Un parámetro que pide el pensamiento del modelo o un razonamiento paso a paso puede provocar un rechazo `reasoning_extraction`. Consulta [Mantén el razonamiento en bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).

<AccordionGroup>
  <Accordion title="Ejemplo de una buena descripción de herramienta">
    ```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="Ejemplo de una descripción de herramienta deficiente">
    ```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>

La buena descripción explica claramente qué hace la herramienta, cuándo usarla, qué datos devuelve y qué significa el parámetro `ticker`. La descripción deficiente es demasiado breve y deja a Claude con muchas preguntas abiertas sobre el comportamiento y el uso de la herramienta.

<Tip>
  Para una guía más profunda sobre el diseño de herramientas (consolidación, nomenclatura y forma de las respuestas), consulta [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents).
</Tip>

## Proporcionar ejemplos de uso de herramientas

Puedes proporcionar ejemplos concretos de entradas de herramientas válidas para ayudar a Claude a entender cómo usar tus herramientas de manera más efectiva. Esto es particularmente útil para herramientas complejas con objetos anidados, parámetros opcionales o entradas sensibles al formato.

### Uso básico

Agrega un campo opcional `input_examples` a tu definición de herramienta con un arreglo de objetos de entrada de ejemplo. Cada ejemplo debe ser válido según el `input_schema` de la herramienta:

<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"
            // Demuestra que 'unit' es 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",
  					// Demuestra que 'unit' es 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>

Los ejemplos se incluyen en la indicación junto con el esquema de tu herramienta, mostrando a Claude patrones concretos de llamadas a herramientas bien formadas. Esto ayuda a Claude a entender cuándo incluir parámetros opcionales, qué formatos usar y cómo estructurar entradas complejas.

### Requisitos y limitaciones

* **Validación de esquema** - Cada ejemplo debe ser válido según el `input_schema` de la herramienta. Los ejemplos no válidos devuelven un error 400
* **No compatible con herramientas del lado del servidor ni con conjuntos de herramientas de cliente** - Los ejemplos de entrada funcionan en herramientas de cliente definidas por el usuario y con esquema de Anthropic, excepto los conjuntos de herramientas de [uso de computadora](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool) y [uso de navegador](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool), pero no en herramientas de servidor como la búsqueda web o la ejecución de código
* **Costo en tokens** - Los ejemplos se suman a los tokens de la indicación: \~20–50 tokens para ejemplos simples, \~100–200 tokens para objetos anidados complejos

## Controlar la salida de Claude

### Forzar el uso de herramientas

En algunos casos, es posible que quieras que Claude use una herramienta específica para responder la pregunta del usuario, incluso si Claude de otro modo respondería directamente sin llamar a una herramienta. Puedes hacerlo especificando la herramienta en el campo `tool_choice` de la solicitud.

No todos los modelos y configuraciones admiten el uso forzado de herramientas. Donde no se admite, `tool_choice: {"type": "any"}` y `tool_choice: {"type": "tool", "name": "..."}` fallan, mientras que `tool_choice: {"type": "auto"}` (el valor predeterminado) y `tool_choice: {"type": "none"}` siguen funcionando:

| Modelo o configuración                                                                                                                     | Restricción                                                                                                           | Qué usar en su lugar                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Pensamiento extendido](https://platform.claude.com/docs/es/build-with-claude/extended-thinking) manual (`thinking: {type: "enabled"}`)    | `any` y `tool` no son compatibles y producen un error                                                                 | `auto` o `none`. El [pensamiento adaptativo](https://platform.claude.com/docs/es/build-with-claude/thinking) en sí no bloquea el uso forzado de herramientas (los modelos con el pensamiento activado de forma predeterminada, como Claude Opus 5 y Claude Haiku 5.5, lo aceptan, pero una llamada forzada omite el pensamiento: la respuesta comienza con la llamada a la herramienta y no tiene bloque `thinking`); los modelos de la siguiente fila rechazan el uso forzado de herramientas independientemente de la configuración de pensamiento |
| Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y [Claude Mythos 5.1](https://platform.claude.com/docs/es/models/mythos-5-1/overview) | `any` y `tool` devuelven un [error 400](https://platform.claude.com/docs/es/api/errors#forced-tool-use-not-supported) | `auto` con [uso estricto de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/strict-tool-use) para garantizar entradas de herramientas válidas según el esquema, o [salidas estructuradas](https://platform.claude.com/docs/es/build-with-claude/structured-outputs) cuando necesites una respuesta con una forma JSON fija. El prompt sigue influyendo en qué herramienta elige `auto`. `none` también es compatible                                                                                                     |

En los modelos que lo admiten, las líneas resaltadas son la única diferencia con respecto a una solicitud estándar de uso de herramientas:

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

Al trabajar con el parámetro `tool_choice`, hay cuatro opciones posibles:

* `auto` permite que Claude determine si llamar o no a alguna de las herramientas proporcionadas. Este es el valor predeterminado cuando se proporcionan `tools`.
* `any` le indica a Claude que debe usar una de las herramientas proporcionadas, pero no fuerza una herramienta en particular.
* `tool` fuerza a Claude a usar siempre una herramienta en particular.
* `none` impide que Claude use cualquier herramienta. Este es el valor predeterminado cuando no se proporcionan `tools`.

<Note>
  Al usar el [almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#what-invalidates-the-cache), los cambios en el parámetro `tool_choice` invalidarán los bloques de mensajes almacenados en caché. Las definiciones de herramientas y las indicaciones del sistema permanecen en caché, pero el contenido de los mensajes debe reprocesarse.
</Note>

Este diagrama ilustra cómo funciona cada opción:

<Frame>
  ![Diagrama de tres opciones de tool\_choice: auto (una herramienta o una respuesta simple), any (una de las herramientas) y tool (la herramienta nombrada)](https://platform.claude.com/docs/es/images/tool_choice.svg)
</Frame>

Ten en cuenta que cuando tienes `tool_choice` como `any` o `tool`, la API prerrellena el mensaje del asistente para forzar el uso de una herramienta. Esto significa que los modelos no emitirán una respuesta o explicación en lenguaje natural antes de los bloques de contenido `tool_use`, incluso si se les pide explícitamente que lo hagan.

Las pruebas han demostrado que esto no debería reducir el rendimiento. Si deseas que el modelo proporcione contexto o explicaciones en lenguaje natural y al mismo tiempo solicitar que el modelo use una herramienta específica, puedes usar `{"type": "auto"}` para `tool_choice` (el valor predeterminado) y agregar instrucciones explícitas en un mensaje de `user`. Por ejemplo: `What's the weather like in London? Use the get_weather tool in your response.`

Forzar una herramienta también omite el pensamiento en todos los modelos que aceptan el uso forzado de herramientas: la respuesta comienza con el bloque `tool_use` y no tiene bloque `thinking`. Para permitir que el modelo piense antes de llamar a la herramienta, usa `auto` con una instrucción en el prompt de la misma manera.

<Tip>
  **Llamadas a herramientas garantizadas con herramientas estrictas**

  En los modelos que admiten el uso forzado de herramientas, combina `tool_choice: {"type": "any"}` con el [uso estricto de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/strict-tool-use) para garantizar tanto que se llame a una de tus herramientas como que las entradas de la herramienta sigan estrictamente tu esquema. Establece `strict: true` en tus definiciones de herramientas para habilitar la validación de esquema.
</Tip>

### Respuestas del modelo con herramientas

Al usar herramientas, Claude a menudo comenta lo que está haciendo o responde de forma natural al usuario antes de llamar a las herramientas.

Por ejemplo, dada la indicación "¿Cómo está el clima en San Francisco ahora mismo y qué hora es allí?", Claude podría responder con:

```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" }
    }
  ]
}
```

Este estilo de respuesta natural ayuda a los usuarios a entender lo que Claude está haciendo y crea una interacción más conversacional. Puedes guiar el estilo y el contenido de estas respuestas a través de tus indicaciones del sistema y proporcionando `<examples>` en tus indicaciones.

Es importante tener en cuenta que Claude puede usar diversas formulaciones y enfoques al explicar sus acciones. Tu código debe tratar estas respuestas como cualquier otro texto generado por el asistente y no depender de convenciones de formato específicas.

## Próximos pasos

<CardGroup>
  <Card href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/handle-tool-calls" title="Manejar llamadas a herramientas">
    Analiza bloques tool\_use y da formato a respuestas tool\_result.
  </Card>

  <Card href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-runner" title="Tool Runner (SDK)">
    Deja que el SDK maneje el bucle agéntico automáticamente.
  </Card>

  <Card href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference" title="Referencia de herramientas">
    Directorio de herramientas proporcionadas por Anthropic y propiedades opcionales.
  </Card>
</CardGroup>