Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Tablas de síntoma a solución para los errores más comunes del uso de herramientas. Cada solución hace referencia cruzada a la página que documenta la funcionalidad correspondiente.
| 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 por QUÉ hacen. Consulta Definir herramientas. |
| 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. Agrega input_examples para concretar el uso previsto. |
| Claude llama con tipos de parámetros incorrectos | El modelo está adivinando ante un esquema ambiguo | Agrega strict: true (si tu esquema está en el subconjunto compatible) o agrega input_examples. |
| Síntoma | Causa probable | Solución |
|---|---|---|
| Parámetro que no existe en tu esquema | Sobregeneración del modelo sin modo estricto | Agrega strict: true si tu esquema está en el subconjunto compatible. |
| Valores de parámetros fuera de tu enum | Falta el modo estricto o el enum es demasiado grande | Reduce el enum o agrega input_examples que muestren opciones válidas. |
| Síntoma | Causa probable | Solución |
|---|---|---|
| Claude llama a las herramientas secuencialmente cuando sería mejor en paralelo | Formato del historial de mensajes | Envía múltiples bloques tool_result en UN solo mensaje de usuario, no uno por turno. Consulta Uso de herramientas en paralelo. |
disable_parallel_tool_use parece ignorarse | Se configuró demasiado tarde en la conversación | Debe configurarse en la solicitud que devuelve tool_use. Configurarlo en una solicitud posterior no tiene efecto sobre llamadas a herramientas anteriores. |
| 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 interrupción cache_control antes del punto de variación. Consulta Uso de herramientas con almacenamiento en caché de prompts. |
| Agregar una herramienta a mitad de la conversación rompe la caché | Herramienta antepuesta al arreglo de herramientas | Usa defer_loading: true con búsqueda de herramientas para anexar la herramienta en línea en lugar de modificar el inicio del arreglo. |
| 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 de usuario | Devuelve un tool_result por cada bloque tool_use en la respuesta del asistente. Coloca los bloques tool_result antes de cualquier texto. Consulta Manejar llamadas a herramientas y Uso de herramientas en paralelo. |
was found without a corresponding <name>_tool_result block | El turno anterior del asistente tiene un bloque server_tool_use sin bloque de resultado (con mayor frecuencia, Claude lo llamó junto con una herramienta de cliente), y tu siguiente mensaje de usuario finalizó ese turno (por ejemplo, con texto después de los bloques tool_result) o la solicitud de reanudación ya no define esa herramienta de servidor (el mensaje entonces termina con but no <name> tool was provided) | Envía un mensaje de usuario que contenga solo los bloques tool_result para los ids de tool_use de cliente y mantén el mismo arreglo tools. Consulta Razones de detención y respaldo. |
Input schema is not compatible with strict mode: string patterns are not supported | Uso de pattern con strict: true | Elimina el patrón o quita strict: true. La palabra clave pattern aún no está en el subconjunto compatible de JSON Schema. |
All tools have defer_loading: true | No hay herramientas visibles para el modelo | Al menos una herramienta debe cargarse de inmediato. La herramienta de búsqueda de herramientas en sí nunca debe tener defer_loading: true. |
Si una solicitud falla con un invalid_request_error 400 cuyo mensaje contiene `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified al continuar una conversación después de una llamada a herramienta, tu aplicación está alterando los bloques de pensamiento del asistente antes de enviarlos de vuelta. Envía el mensaje completo del asistente sin cambios y luego anexa tu tool_result.
Consulta Los bloques de pensamiento no se pueden modificar para ver el error completo y los pasos de solución.
| Síntoma | Causa probable | Solución |
|---|---|---|
| Claude se niega a actuar sobre un resultado de herramienta, o pide al usuario que confirme instrucciones que provinieron de él | Tus propias instrucciones se están entregando dentro del contenido de tool_result | Claude está entrenado para tratar las instrucciones dentro de los resultados de herramientas como contenido de terceros potencialmente no confiable. Mueve tus instrucciones fuera del resultado de la herramienta: envíalas en un turno de user después del bloque tool_result, o (en Claude Opus 4.8 y posteriores) en un mensaje de sistema a mitad de conversación. Limita el resultado de la herramienta solo a los datos. Consulta Mitigar jailbreaks e inyecciones de prompts. |
| Síntoma | Causa | Solución |
|---|---|---|
| La comparación de cadenas en las entradas de herramientas falla con modelos más recientes | El escapado de Unicode y de barras diagonales difiere entre versiones del modelo | Analiza con json.loads() o JSON.parse(). Nunca hagas comparación de cadenas sin procesar sobre la entrada serializada. |
Escribe esquemas y descripciones que guíen a Claude hacia la herramienta correcta.
Ejecuta herramientas y devuelve resultados en el formato de mensaje requerido.
Directorio completo de herramientas con esquema de Anthropic y sus cadenas de versión.
Was this page helpful?