Mejores prácticas para el uso de herramientas

Prácticas numeradas para el diseño de esquemas, manejo de errores y bucles de herramientas de múltiples turnos: un resumen de toda la sección que puedes usar como lista de verificación antes de implementar una integración de uso de herramientas basada en el SDK oficial de Python de anthropic.

Cómo usar esta lista

• Lee de principio a fin la primera vez: el diseño del esquema y tool_choice vienen primero porque afectan si Claude llama a la herramienta correcta, antes de que llegues a la mecánica del bucle.
• Trata los elementos 1-2 como trabajo de diseño (hecho una vez por herramienta), los elementos 3-6 como comportamiento en tiempo de solicitud y en tiempo de bucle (hecho en cada llamada), y los elementos 7-9 como preocupaciones de escalado que adoptarás una vez que el conjunto de herramientas o el tráfico crezcan.
• Vuelve a esta página cada vez que agregues una nueva herramienta o veas que Claude elige la herramienta incorrecta, elimina un tool_result o se repite más de lo esperado.
• Combina esto con las páginas más detalladas vinculadas en "Relacionado": esta página es deliberadamente concisa; las páginas vinculadas contienen las explicaciones completas y ejemplos prácticos.

A - Diseño del esquema

• Dale a cada herramienta un nombre claro y descriptivo. Usa get_weather, no w o tool1; Claude compara tu description con la intención del usuario, y un nombre vago le da menos información para trabajar.
• Escribe descripciones que digan CUÁNDO llamar a la herramienta, no solo lo que hace. "Llama a esto cuando el usuario pregunte sobre los precios actuales" supera a una descripción que solo indica la funcionalidad; los modelos recientes de Claude recurren a las herramientas de forma más conservadora por defecto, por lo que una descripción prescriptiva y con palabras clave mejora notablemente la precisión de la llamada.
• Dale a cada propiedad de input_schema su propia description. Claude lee las descripciones por propiedad para decidir qué valor extraer y cómo formatearlo; una propiedad indocumentada es una propiedad sobre la que Claude tiene que adivinar.
• Usa enum para parámetros de elección fija. Si un parámetro siempre toma uno de un conjunto conocido de valores (por ejemplo, "unit": ["celsius", "fahrenheit"]), restringe con enum en lugar de dejarlo como texto de formato libre.
• Marca solo los campos verdaderamente requeridos en required. Marcar demasiados campos como requeridos obliga a Claude a fabricar un valor o a hacer una pregunta aclaratoria innecesaria cuando el campo no se aplica.
• Establece "strict": true cuando necesites una validación de esquema exacta. Agrégalo en el nivel superior de la definición de la herramienta junto con additionalProperties: false y required; esto hace que tool_use.input se valide exactamente contra el esquema en lugar de desviarse en casos extremos.

B - Mantén el conjunto de herramientas enfocado

• No registres más herramientas de las que la tarea necesita. Demasiadas herramientas, nombres vagos o descripciones superpuestas pueden hacer que Claude elija la herramienta incorrecta o que no llame a ninguna; un conjunto de herramientas grande e indiferenciado es peor para la precisión que uno pequeño y bien descrito.
• Verifica la superposición de descripciones antes de agregar una nueva herramienta. Si dos herramientas podrían satisfacer plausiblemente la misma solicitud, ajusta el lenguaje "llama a esto cuando" en cada una hasta que sean mutuamente distinguibles.

C - tool_choice

• Por defecto, usa {"type": "auto"} para agentes de propósito general. Deja que Claude decida si llamar a una herramienta y cuál, basándose en la conversación.
• Usa {"type": "any"} cuando el turno deba terminar en alguna acción pero no te importe qué herramienta. Esto garantiza una llamada a la herramienta sin elegir en nombre de Claude.
• Usa {"type": "tool", "name": "..."} para forzar una herramienta específica. Recurre a esto cuando el flujo de trabajo requiera una llamada a función particular, independientemente de lo que Claude elegiría de otra manera.
• Usa {"type": "none"} para suprimir temporalmente las llamadas a herramientas sin eliminar tools de la solicitud. Eliminar las definiciones de herramientas por completo invalida el almacenamiento en caché de la solicitud; none mantiene las definiciones en su lugar y simplemente evita que ese turno en particular llame a una herramienta.
• Agrega disable_parallel_tool_use: true a cualquier valor de tool_choice cuando tu código no pueda manejar más de una llamada a herramienta por turno. Funciona junto con auto, any, tool o none y limita a Claude a una sola llamada a herramienta en esa respuesta.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[weather_tool, calculate_tool],
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=[{"role": "user", "content": "What's the weather in Austin, TX?"}],
)

D - Manejo de errores en bloques tool_result

• Devuelve is_error: true en caso de fallo de la herramienta en lugar de eliminar el resultado o generar una excepción. Claude puede entonces reintentar la llamada, probar una herramienta diferente o pedir una aclaración al usuario; un tool_result faltante o una excepción no manejada deja la conversación en un estado roto.

def run_tool(tool_use):
    try:
        output = execute(tool_use.name, tool_use.input)
        return {
            "type": "tool_result",
            "tool_use_id": tool_use.id,
            "content": str(output),
        }
    except Exception as exc:
        return {
            "type": "tool_result",
            "tool_use_id": tool_use.id,
            "content": f"Error: {exc}",
            "is_error": True,
        }

E - Higiene del bucle de múltiples turnos

• Agrega el response.content completo de nuevo a messages, no solo el texto extraído. La API necesita que los bloques tool_use se conserven en el turno del asistente; eliminarlos para dejar solo el contenido de texto rompe la siguiente solicitud.
• Protege cada bucle con un límite de max_iterations. Un bucle de uso de herramientas sin límite puede descontrolarse si Claude sigue llamando a herramientas sin producir una respuesta final.
• Maneja stop_reason == "pause_turn" reenviando la conversación tal cual. Este motivo de detención significa que una herramienta del lado del servidor alcanzó su límite de iteración interno; no inyectes un mensaje extra de "Continuar"; la API se reanuda automáticamente porque detecta el bloque server_tool_use final.

messages = [{"role": "user", "content": "What's the weather in Austin, TX?"}]
 
for _ in range(max_iterations := 8):
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=[weather_tool],
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})
 
    if response.stop_reason == "pause_turn":
        continue  # reenviar tal cual, sin mensaje "Continuar" inyectado
 
    if response.stop_reason != "tool_use":
        break
 
    tool_results = [run_tool(block) for block in response.content if block.type == "tool_use"]
    messages.append({"role": "user", "content": tool_results})

F - Llamadas a herramientas paralelas

• Espera y maneja múltiples bloques tool_use en un solo turno. Claude puede solicitar varias herramientas en paralelo por defecto; ejecútalas concurrentemente cuando sea práctico en lugar de asumir exactamente una llamada por turno.
• Devuelve TODOS los bloques tool_result juntos en un solo mensaje user. Nunca los dividas en varios mensajes; hacerlo puede degradar el comportamiento futuro de las llamadas paralelas de Claude.
• Haz coincidir cada tool_use_id que Claude envió con un tool_result, incluidas las llamadas fallidas. Un bloque tool_use sin un tool_result correspondiente (incluso uno con is_error: true) deja el turno incompleto.

G - Escalado a muchas herramientas

• Adopta la herramienta de búsqueda de herramientas (Tool Search Tool) una vez que una biblioteca de herramientas crezca a un rango de docenas a cientos. Usa tool_search_tool_regex_20251119 o tool_search_tool_bm25_20251119 con defer_loading: true en herramientas poco usadas para reducir el uso de tokens aproximadamente en un 85%.
• Mantén la herramienta de búsqueda en sí y al menos otra herramienta sin diferir. Diferir todas las herramientas, incluida la herramienta de búsqueda, hace que la solicitud sea 400; Claude necesita al menos una herramienta cargada inmediatamente para razonar.
• Prefiere el conector MCP sobre un wrapper del lado del cliente para capacidades remotas/alojadas. Cuando ya existe un servidor MCP adecuado, usa mcp_servers más una entrada mcp_toolset coincidente (beta mcp-client-2025-11-20) en lugar de reimplementar un cliente que llama a la misma API remota.

H - Almacenamiento en caché de solicitudes con herramientas

• Recuerda que las definiciones de herramientas se renderizan primero en la solicitud, antes del sistema y los mensajes. Agregar, eliminar o reordenar herramientas invalida el nivel de caché de herramientas/sistema; alternar tool_choice por sí solo no lo hace.
• Mantén el orden de las herramientas determinista si construyes la lista tools dinámicamente. Ordena por nombre (o por otra clave estable) para que el mismo conjunto de herramientas siempre se serialice en el mismo orden y no invalide innecesariamente la caché.

I - Análisis JSON

• Siempre lee tool_use.input a través del objeto analizado del SDK, nunca comparándolo con una cadena sin procesar. Los modelos recientes de Claude pueden escapar Unicode o barras diagonales de manera diferente en el JSON generado, por lo que la comparación de cadenas con la carga útil sin procesar es frágil de una manera que un objeto analizado no lo es.

Preguntas frecuentes

Relacionado

• Conceptos básicos del uso de herramientas - el viaje completo de solicitud/respuesta que asumen estas prácticas
• Definición de esquemas de herramientas con nombre, descripción e input_schema - el análisis profundo detrás de los elementos de diseño de esquemas anteriores
• Referencia de opciones de tool_choice - referencia completa para los cuatro modos de tool_choice
• Construcción de un bucle de uso de herramientas de múltiples turnos - el ejemplo práctico detrás de los elementos de higiene del bucle anteriores
• Ejecución de llamadas a herramientas paralelas en un solo turno - la explicación completa del manejo paralelo de tool_use
• Escalado a cientos de herramientas con la herramienta de búsqueda de herramientas - el análisis profundo detrás del elemento de escalado anterior

Versiones de la pila: Escrito para la línea de modelos de Claude actual a partir de ~junio de 2026: Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5, y el SDK oficial de Python de anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.