Definir herramientas

Elegir un modelo

Usa el último modelo Claude Opus (4.7) para herramientas complejas y consultas ambiguas; maneja múltiples herramientas mejor y busca aclaraciones cuando es necesario.

Usa modelos Claude Haiku para herramientas directas, pero ten en cuenta que pueden inferir parámetros faltantes.

Especificar herramientas del cliente

Las herramientas del cliente (tanto esquema Anthropic como definidas por el usuario) se especifican en el parámetro de nivel superior tools de la solicitud de API. Cada definición de herramienta incluye:

Para el conjunto completo de propiedades opcionales disponibles en cualquier definición de herramienta, incluyendo cache_control, strict, defer_loading y allowed_callers, consulta la referencia de herramientas.

Indicación del sistema de uso de herramientas

Cuando llamas a la API de Claude con el parámetro tools, la API construye un indicador del sistema especial a partir de las definiciones de herramientas, la configuración de herramientas y cualquier indicador del sistema especificado por el usuario. El indicador construido está diseñado para instruir al modelo que use la(s) herramienta(s) especificada(s) y proporcione el contexto necesario para que la herramienta funcione correctamente:

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 definiciones de herramientas

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

• Proporciona descripciones extremadamente detalladas. Este es, con mucho, 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 la herramienta no devuelve si el nombre de la herramienta no es claro. Cuanto más contexto puedas dar a Claude sobre tus herramientas, mejor será a la hora de decidir cuándo y cómo usarlas. Apunta a al menos 3-4 oraciones por descripción de herramienta, más si la herramienta es compleja.
• Prioriza 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 por esquema. Consulta Proporcionar ejemplos de uso de herramientas 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, más capaces, reducen la ambigüedad de selección y hacen que tu superficie de herramientas sea más fácil de navegar para Claude.
• Usa espacios de nombres significativos en nombres de herramientas. Cuando tus herramientas abarcan múltiples servicios o recursos, prefija los nombres con el servicio (por ejemplo, github_list_prs, slack_send_message). Esto hace que la selección de herramientas sea inequívoca a medida que tu biblioteca crece, y es especialmente importante cuando usas búsqueda de herramientas.
• Diseña respuestas de herramientas para devolver 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 próximo paso. Las respuestas infladas desperdician contexto y hacen que sea más difícil para Claude extraer lo que importa.

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.

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 input_examples opcional a tu definición de herramienta con un array de objetos de entrada de ejemplo. Cada ejemplo debe ser válido según el input_schema de la herramienta:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

Los ejemplos se incluyen en el indicador junto a tu esquema de herramienta, mostrando a Claude patrones concretos para llamadas de 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 inválidos devuelven un error 400
• No compatible con herramientas del lado del servidor - Los ejemplos de entrada funcionan en herramientas del cliente definidas por el usuario y esquema Anthropic, pero no en herramientas del servidor como búsqueda web o ejecución de código
• Costo de tokens - Los ejemplos se suman a los tokens del indicador: ~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 desees que Claude use una herramienta específica para responder la pregunta del usuario, incluso si Claude respondería directamente sin llamar a una herramienta. Puedes hacer esto especificando la herramienta en el campo tool_choice así:

tool_choice = {"type": "tool", "name": "get_weather"}

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

• auto permite a Claude decidir si llamar a cualquiera de las herramientas proporcionadas o no. Este es el valor predeterminado cuando se proporcionan tools.
• any le dice 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 evita que Claude use cualquier herramienta. Este es el valor predeterminado cuando no se proporcionan tools.

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

Ten en cuenta que cuando tienes tool_choice como any o tool, la API rellena previamente el mensaje del asistente para forzar el uso de una herramienta. Esto significa que los modelos no emitirán una respuesta en lenguaje natural o explicación antes de 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 en lenguaje natural o explicaciones mientras aún solicita que el modelo use una herramienta específica, puedes usar {"type": "auto"} para tool_choice (el predeterminado) y agregar instrucciones explícitas en un mensaje user. Por ejemplo: What's the weather like in London? Use the get_weather tool in your response.

Respuestas del modelo con herramientas

Cuando usas herramientas, Claude a menudo comentará sobre lo que está haciendo o responderá naturalmente al usuario antes de invocar herramientas.

Por ejemplo, dada la solicitud "What's the weather like in San Francisco right now, and what time is it there?", Claude podría responder con:

{
  "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 qué está haciendo Claude y crea una interacción más conversacional. Puedes guiar el estilo y el contenido de estas respuestas a través de tus indicadores del sistema y proporcionando <examples> en tus indicadores.

Es importante notar que Claude puede usar varias frases 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