MessagesHerramientas
Solución de problemas del uso de herramientas
Corrige los errores más comunes del 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 del "tool use" (uso de herramientas). Cada solución hace referencia cruzada a la página que documenta la funcionalidad.
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 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 adivina ante un esquema ambiguo | Agrega strict: true (si tu esquema está en el subconjunto compatible) o agrega input_examples. |
Claude inventa parámetros de herramientas
| 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. |
Las llamadas a herramientas en paralelo no funcionan
| Síntoma | Causa probable | Solución |
|---|---|---|
| Claude llama a las herramientas secuencialmente cuando en paralelo sería mejor | 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 las llamadas a herramientas anteriores. |
La caché se invalida constantemente
| Síntoma | Causa probable | Solución |
|---|---|---|
| Cada solicitud es un fallo de caché | tool_choice, la configuración de pensamiento o output_config.effort varían entre solicitudes | Mantén tool_choice estable o coloca el punto de interrupción cache_control antes del punto de variación; mantén constantes la configuración de pensamiento y el nivel de esfuerzo durante toda la vida de una conversación en caché. Consulta Uso de herramientas con almacenamiento en caché de prompts y Pensamiento y almacenamiento en caché de prompts. |
| Agregar una herramienta a mitad de la conversación rompe la caché | La herramienta se antepuso al arreglo de herramientas | Usa defer_loading: true con la búsqueda de herramientas para agregar la herramienta en línea en lugar de modificar el inicio del arreglo. |
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 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 (lo más frecuente es que Claude lo haya llamado junto con una herramienta de cliente), y o bien tu siguiente mensaje de usuario terminó ese turno (por ejemplo, con texto después de los bloques tool_result) o bien 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 del cliente y mantén el mismo arreglo tools. Consulta Razones de detención y alternativas. |
Unsupported regex feature in pattern field: ... | Un pattern en el input_schema de una herramienta estricta usa una característica de regex que el modo estricto no puede compilar, como una retrorreferencia, un lookaround, un límite de palabra o un rango {n,m} grande | Simplifica el patrón. Se admiten patrones anclados con cuantificadores básicos, clases de caracteres y grupos; consulta Limitaciones de JSON Schema. |
All tools have defer_loading: true | Ninguna herramienta es visible 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. |
Error: los bloques de pensamiento no se pueden modificar
Si una solicitud falla con un 400 invalid_request_error 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 de vuelta sin cambios y luego agrega tu tool_result.
Consulta Los bloques de pensamiento no se pueden modificar para ver el error completo y los pasos para solucionarlo.
Claude marca los resultados de herramientas como inyección de prompts
| Síntoma | Causa probable | Solución |
|---|---|---|
| Claude se niega a actuar sobre un resultado de herramienta, o pide al usuario que confirme instrucciones que provienen 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. Saca tus instrucciones del resultado de la herramienta: envíalas en un turno user después del bloque tool_result o, en los modelos compatibles, en un mensaje del sistema a mitad de la conversación. Limita el resultado de la herramienta solo a los datos. Consulta Mitigar jailbreaks e inyecciones de prompts. |
Diferencias en el escape de JSON (Opus 4.6+)
| Síntoma | Causa | Solución |
|---|---|---|
| La comparación de cadenas en las entradas de herramientas falla con modelos más nuevos | El escape de Unicode y de barras diagonales difiere entre versiones de modelos | Analiza con json.loads() o JSON.parse(). Nunca hagas coincidencia de cadenas sin procesar sobre la entrada serializada. |
Próximos pasos
Escribe esquemas y descripciones que orienten a Claude hacia la herramienta correcta.
Ejecuta herramientas y devuelve resultados en el formato de mensaje requerido.
Directorio completo de las herramientas proporcionadas por Anthropic y sus cadenas de versión.
Was this page helpful?