Solución de problemas con el uso de herramientas

Corrige los errores más comunes en el uso de herramientas con tablas de diagnóstico de síntoma a solución.

Tablas de síntoma a solución para los errores más comunes en el uso de herramientas. Cada solución hace referencia cruzada a la página que posee la característica.

Claude llama a la herramienta equivocada

Síntoma	Causa probable	Solución
Claude llama a la herramienta A cuando querías la herramienta B	Ambigüedad en la descripción	Afina las descripciones. Diferencia las herramientas por CUÁNDO usarlas, no solo QUÉ hacen. Ver Define tools.
Claude nunca llama a tu herramienta	Colisión de nombres de herramientas o esquema demasiado genérico	Verifica si hay nombres duplicados en tu lista de herramientas. Añade `input_examples` para hacer el uso previsto concreto.
Claude llama con tipos de parámetros incorrectos	El modelo adivina en un esquema ambiguo	Añade `strict: true` (si tu esquema está en el subconjunto compatible) o añade `input_examples`.

Claude inventa parámetros de herramientas

Síntoma	Causa probable	Solución
Parámetro que no existe en tu esquema	Generación excesiva del modelo sin modo estricto	Añade `strict: true` si tu esquema está en el subconjunto compatible.
Valores de parámetros fuera de tu enumeración	Modo estricto faltante o enumeración demasiado grande	Reduce la enumeración o añade `input_examples` mostrando opciones válidas.

Las llamadas de herramientas paralelas no funcionan

Síntoma	Causa probable	Solución
Claude llama a las herramientas secuencialmente cuando lo paralelo sería mejor	Formato del historial de mensajes	Envía múltiples bloques `tool_result` en UN mensaje de usuario, no uno por turno. Ver Parallel tool use.
`disable_parallel_tool_use` parece ignorado	Se establece demasiado tarde en la conversación	Debe establecerse en la solicitud que devuelve `tool_use`. Establecerlo en una solicitud posterior no tiene efecto en las llamadas de herramientas anteriores.

El caché sigue invalidándose

Síntoma	Causa probable	Solución
Cada solicitud es un fallo de caché	`tool_choice` varía entre solicitudes	Mantén `tool_choice` estable o coloca el punto de ruptura `cache_control` antes del punto de variación. Ver Tool use with prompt caching.
Añadir una herramienta a mitad de la conversación rompe el caché	Herramienta antepuesta al array de herramientas	Usa `defer_loading: true` con búsqueda de herramientas para añadir la herramienta en línea en lugar de modificar el encabezado del array.

Errores en el momento de la solicitud

Error	Causa	Solución
`tool_use ids were found without tool_result blocks immediately after`	Falta `tool_result` para algunos ids de `tool_use`, o `tool_result` no es el primer bloque de contenido en el mensaje del usuario	Devuelve un `tool_result` para cada bloque `tool_use` en la respuesta del asistente. Coloca bloques `tool_result` antes de cualquier texto. Ver Handle tool calls y Parallel tool use.
`Input schema is not compatible with strict mode: string patterns are not supported`	Usando `pattern` con `strict: true`	Elimina el patrón o suelta `strict: true`. La palabra clave `pattern` aún no está en el subconjunto de JSON Schema compatible.
`All tools have defer_loading: true`	Ninguna herramienta visible para el modelo	Al menos una herramienta debe cargarse inmediatamente. La herramienta de búsqueda de herramientas en sí nunca debe tener `defer_loading: true`.

Diferencias de escape JSON (Opus 4.6+)

Síntoma	Causa	Solución
La comparación de cadenas en entradas de herramientas falla con modelos más nuevos	El escape de Unicode y barra diagonal difiere entre versiones de modelo	Analiza con `json.loads()` o `JSON.parse()`. Nunca hagas coincidencia de cadenas sin procesar en entrada serializada.

Próximos pasos

Define tools

Escribe esquemas y descripciones que dirijan a Claude hacia la herramienta correcta.

Handle tool calls

Ejecuta herramientas y devuelve resultados en el formato de mensaje requerido.

Tool reference

Directorio completo de herramientas de esquema Anthropic y sus cadenas de versión.

Was this page helpful?

ConstruirHerramientas