--- title: Solución de problemas del uso de herramientas url: https://platform.claude.com/docs/es/agents-and-tools/tool-use/troubleshooting-tool-use description: 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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/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. 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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/strict-tool-use). | | 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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/parallel-tool-use). | | `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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-use-with-prompt-caching) y [Pensamiento y almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-and-prompt-caching). | | 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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/handle-tool-calls) y [Uso de herramientas en paralelo](https://platform.claude.com/docs/es/agents-and-tools/tool-use/parallel-tool-use). | | `was found without a corresponding _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 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](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#tool-use). | | `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](https://platform.claude.com/docs/es/build-with-claude/structured-outputs#json-schema-limitations). | | `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](https://platform.claude.com/docs/es/api/errors#thinking-blocks-cannot-be-modified) 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](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages). Limita el resultado de la herramienta solo a los datos. Consulta [Mitigar jailbreaks e inyecciones de prompts](https://platform.claude.com/docs/es/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection). | ## Diferencias de escape de JSON entre versiones del modelo | 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.