SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor

Límite de uso de herramientas de Claude en este turno

El mensaje indica que Claude agotó las llamadas a herramientas permitidas en un turno, no la cuota del plan. Aprende a continuar la tarea con un turno nuevo.

Qué significa el límite de uso de herramientas para este turno

El límite de uso de herramientas para este turno significa que Claude detuvo la respuesta a mitad porque se quedó sin llamadas a herramientas disponibles, no porque su cuenta se haya quedado sin uso. Todo lo que encontró antes de detenerse sigue en la conversación. Envíe otro mensaje para pedirle que continúe. Así se inicia un turno nuevo con un presupuesto nuevo.

En el Agent SDK, un turno es una pasada del bucle del agente. Claude genera una respuesta que contiene llamadas a herramientas, el cliente ejecuta esas herramientas y los resultados se devuelven a Claude para que tome la siguiente decisión. El ciclo se repite sin devolverle el control. El bucle termina cuando Claude genera una respuesta sin llamadas a herramientas. El límite de turnos del SDK cuenta cada pasada, incluida la respuesta final sin llamadas a herramientas.

El límite de uso de tu plan es un control independiente

El límite del plan cuenta lo que has usado durante un periodo determinado. La página del centro de ayuda de Anthropic sobre mensajes de error, consultada el 9 de noviembre de 2026, indica Approaching session limit cuando te acercas al límite y 5-hour limit reached - resets [time] cuando lo superas. El límite semanal muestra mensajes similares que indican un día y una hora de restablecimiento. En ambos casos, el mensaje incluye una hora. Sin créditos de uso, esperar hasta esa hora resuelve el problema; nada de lo que escribas mientras tanto ayuda. Si tienes activados los créditos de uso en un plan de pago, la página indica que el trabajo continúa usando créditos y el mensaje muestra 5-hour limit resets [time] - continuing with usage credits. Esa continuidad termina cuando alcanzas el límite de gasto mensual o se agota el saldo de créditos con la recarga automática desactivada. Las cuentas Ultra verificadas no tienen un límite de sesión de cinco horas, pero los límites semanales siguen aplicándose.

El mensaje de uso de herramientas funciona de forma opuesta. Aparece en mitad de una tarea y un solo mensaje de seguimiento permite continuar el trabajo de inmediato. Las llamadas a herramientas que ya se han realizado siguen contando para el uso del plan. Continuar no restablece la cuota, y los créditos de uso también pueden permitir que el trabajo continúe después de alcanzar un límite del plan. Para el caso de la cuota, qué hacer cuando Claude indica que se ha alcanzado el límite enumera las opciones, y cómo se calculan los límites de uso de Claude explica los periodos en los que se basan.

Por qué un turno tiene un presupuesto de herramientas

Cada llamada a una herramienta consume contexto. La llamada se envía, la herramienta se ejecuta y el resultado completo vuelve a la conversación. Leer un archivo grande o ejecutar un comando con una salida extensa puede consumir miles de tokens en un solo paso, y ese texto permanece en el contexto durante el resto de la sesión. La documentación sobre el bucle de agentes de Anthropic explica claramente la consecuencia: el contexto se acumula entre turnos, por lo que una sesión con muchas llamadas a herramientas contiene mucho más que una sesión corta.

El presupuesto del turno detiene un bucle que ya no progresa. Un agente que busca, lee, vuelve a buscar y sigue sin encontrar nada continuará haciéndolo hasta que algo lo interrumpa. El presupuesto es esa interrupción. Te devuelve el control en un punto desde el que puedes redirigir el trabajo. Esto consume mucho menos que dejar que el bucle llegue al final de la ventana de contexto.

Dónde se muestra este límite en la API

La documentación pública de errores de Anthropic no proporciona un número de llamadas a herramientas por turno para la aplicación de chat de Claude, por lo que cualquier cifra exacta que leas es una suposición de otra persona. La API (interfaz de programación de aplicaciones) documenta un límite del mismo tipo, y esa documentación muestra el comportamiento real.

El campo stop_reason de una respuesta de Messages API indica por qué se detuvo la generación. Los valores documentados son end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal y model_context_window_exceeded. Dos de ellos describen la situación de esta guía.

pause_turn se devuelve cuando el bucle de muestreo del servidor alcanza su límite de iteraciones mientras ejecuta herramientas del servidor, como la búsqueda web. A fecha del 25 de octubre de 2026, la página sobre motivos de detención y alternativa indica que el valor predeterminado es de 10 iteraciones por solicitud. La solución documentada consiste en enviar la respuesta sin cambios como mensaje del assistant, para que Claude continúe desde donde se detuvo. No debes añadir un mensaje nuevo del usuario que le pida continuar: el ejemplo documentado envía únicamente el mensaje original del usuario seguido del contenido pausado del assistant.

max_tokens significa que la respuesta alcanzó el límite de tokens de salida establecido en la solicitud. Si se trunca dentro de un bloque incompleto de uso de herramientas, la llamada a la herramienta no se puede ejecutar, y la respuesta documentada consiste en reintentar con un max_tokens mayor.

Consulta los valores actuales en la página sobre motivos de detención y alternativas en lugar de confiar en los valores escritos aquí. Los valores predeterminados de esa página cambian, y una cifra obsoleta es peor que no indicar ninguna.

Qué hace que un chat agote las llamadas a herramientas

  • Una pregunta sin un punto natural de finalización. "Find everything written about X" no proporciona al modelo ninguna indicación de que la búsqueda haya terminado.
  • Lecturas repetidas del mismo material, porque la respuesta no está donde el modelo esperaba encontrarla.
  • Resultados grandes de las herramientas. Una página web larga o un archivo grande consume el espacio que necesita el resto del turno.
  • Varios trabajos independientes en un mismo mensaje. Cada trabajo necesita sus propias llamadas a herramientas y todas consumen el mismo presupuesto.
  • Conectores y servidores MCP (protocolo de contexto del modelo) que no utilizas para esta tarea. Una vez cargados, cada uno ocupa espacio en la conversación y ofrece al modelo más formas de consumir el turno.

Cómo terminar la respuesta

Responde con "continue" o, mejor, con una instrucción breve que indique qué falta. Eso abre un turno nuevo con un presupuesto nuevo. La conversación anterior sigue en el contexto, por lo que Claude continúa el trabajo en lugar de repetir las llamadas a herramientas que ya realizó.

Si se detiene dos veces en el mismo punto, la tarea es demasiado amplia para un solo turno, así que divídela. En lugar de solicitar una auditoría completa de un repositorio, pide primero la lista de archivos y después pregunta por un archivo en cada mensaje. Cuatro turnos pequeños terminan un trabajo que un turno grande no puede completar.

Limita lo que el modelo debe buscar. Proporciona la ruta exacta del archivo o la cadena de error exacta, y pega el registro si ya lo tienes. Pegar un registro cuesta un mensaje. Hacer que el modelo busque ese registro cuesta varias llamadas a herramientas y puede encontrar el archivo equivocado.

Desactiva los conectores que no necesites en ese momento. El centro de ayuda de Anthropic indica que cada conector ocupa espacio en una conversación. Con el ajuste predeterminado Auto, Claude decide qué conectores cargar, mientras que Always available carga todos al principio. Cada conector cargado consume contexto y amplía el conjunto de acciones que el modelo puede elegir. Si mantienes un conjunto grande de conectores, el ajuste On demand los carga sólo después de que Claude busque el adecuado. El mismo razonamiento se aplica a una sesión de programación larga, donde mantener pequeño el contexto de una sesión de Claude Code marca la diferencia entre un agente que termina y uno que se detiene a mitad.

Define el presupuesto de turnos al ejecutar un agente

Si ejecuta Claude desde su propio código, el presupuesto de turnos del bucle es una configuración que controla usted. El Claude Agent SDK (kit de desarrollo de software) expone max_turns en Python y maxTurns en TypeScript. Estos parámetros cuentan los turnos que incluyen llamadas a herramientas y la respuesta final que sólo contiene texto. El valor predeterminado documentado no establece ningún límite.

Cuando se alcanza ese límite, el SDK devuelve un resultado cuyo subtype es error_max_turns. Después, una llamada de una sola ejecución mediante query() genera un error que contiene el texto Reached maximum number of turns. La página del bucle de agentes del Agent SDK también documenta una salida distinta de cero del proceso subyacente de Claude Code para ese error de una sola ejecución. El resultado conserva num_turns y session_id. Por tanto, puede reanudar la misma sesión con un límite superior en lugar de iniciar de nuevo la tarea.

En la CLI (interfaz de línea de comandos), el mismo control es una opción y sólo se aplica al modo de impresión:

claude -p --max-turns 3 "summarise the failing tests"

La referencia de opciones indica que, de forma predeterminada, no hay ningún límite. Con --input-format stream-json, un mensaje que siga en la cola cuando termine el límite permanece en ella e inicia un turno nuevo con su propio límite. Existe una variante equivalente basada en el coste: max_budget_usd en Python y maxBudgetUsd en TypeScript detienen el bucle cuando se alcanza un umbral de gasto, en lugar de hacerlo tras un número de turnos. El gasto de los subagentes cuenta para ese total. El presupuesto se comprueba después de recibir las respuestas del modelo. Por eso, el gasto puede superar el límite debido a la respuesta que lo alcanza y a los subagentes en segundo plano que terminan antes de detenerse. Si ejecuta agentes en un servidor cuyo coste paga mensualmente, merece la pena configurar el control del coste de un agente de IA en un VPS antes de la primera ejecución prolongada.

Una pausa a la espera de aprobación es otra situación. Si el agente se detiene y no se está generando ningún gasto, consulte permission_mode en lugar del número de turnos. En ese caso, una herramienta está esperando una respuesta humana que nunca llega. El modo automático y la configuración de permisos de Claude Code explica qué modos solicitan confirmación y cuáles se ejecutan sin solicitarla.

Cómo comprobar el comportamiento actual

El comportamiento cambia sin previo aviso, por lo que debe tratar cada número de esta guía como un dato fechado y no como un valor fijo. Hay dos lugares que muestran lo que ocurre actualmente.

  • La documentación de la API sobre los motivos de detención, que indica el valor predeterminado de iteraciones de la herramienta del servidor y cómo continuar después de alcanzarlo.
  • La página del centro de ayuda de Anthropic sobre los mensajes de error, que incluye el texto de los límites de uso. Comprobada el 9 de noviembre de 2026, esa página documenta los mensajes de uso de cinco horas y semanales, incluidas las versiones que aparecen cuando se consumen los créditos de uso, y no menciona ningún límite de herramientas por turno. Por eso aquí no se cita ninguna cifra oficial para la aplicación de chat.

Mida sus propias ejecuciones. En Claude Code, /context muestra el uso actual del contexto como una cuadrícula de colores e indica qué herramientas consumen la mayor parte, y /compact resume la conversación hasta ese momento para liberar espacio. En Agent SDK, cada resultado incluye num_turns, por lo que puede comprobar cuántos turnos necesita realmente una tarea típica antes de elegir un límite. Una cifra obtenida de su propia carga de trabajo vale más que una cifra publicada en un foro.

FAQ

¿El límite de uso de herramientas es el mismo que mi límite de uso de Claude?

No. El límite de uso cuenta lo que has consumido durante un intervalo de tiempo e indica cuándo se restablece. Por tanto, la solución es esperar. El mensaje sobre el uso de herramientas detiene una respuesta a mitad porque esa respuesta agotó sus llamadas a herramientas. Al enviar otro mensaje, se inicia inmediatamente un turno nuevo con un presupuesto nuevo. El uso de herramientas sigue contando para el uso incluido en tu plan. cómo se cuentan los límites de uso de Claude explica el caso de la cuota completo.

¿Cómo hago que Claude termine una tarea que detuvo a mitad?

Envía otro mensaje. "Continue" funciona, pero una instrucción que indique qué falta funciona mejor, porque evita que el modelo reconstruya el contexto que ya tiene. Si vuelve a detenerse en el mismo punto, divide la tarea en partes más pequeñas y envía una parte por mensaje. Indicar las rutas exactas de los archivos o pegar directamente el contenido elimina la búsqueda que agotó el presupuesto inicialmente.

¿Qué significa "límite de uso de herramientas" o "limite de uso de ferramentas"?

Son las formulaciones en español y portugués del mismo mensaje. Normalmente aparecen como "límite de uso de herramientas en este turno" o "limite de uso de ferramentas neste turno". El significado es idéntico en todos los idiomas: Claude agotó las llamadas a herramientas permitidas dentro de una sola respuesta y la cuota de tu plan no interviene. La solución también es la misma. Responde solicitando que continúe o divide la solicitud en pasos más pequeños. El límite de facturación aparece en un mensaje distinto, que indica una hora de restablecimiento.

¿Actualizar mi plan aumenta el límite de uso de herramientas de un turno?

El nivel del plan y el presupuesto de herramientas por turno son controles diferentes. Actualizar el plan aumenta cuánto puedes usar durante un intervalo. Ese es el límite que indica una hora de restablecimiento. El número de llamadas a herramientas que puede realizar una sola respuesta depende del bucle que ejecuta el modelo. Anthropic no publica esa cifra para la aplicación de chat. Dividir la tarea en turnos más pequeños es lo que realmente ayuda, con cualquier plan.

¿Por qué mi propio agente se detiene después de sólo unas pocas llamadas a herramientas?

Comprueba si has establecido un límite. El Claude Agent SDK usa max_turns en Python y maxTurns en TypeScript. La interfaz de línea de comandos usa --max-turns en modo de impresión. Cuando se alcanza uno de esos límites, el SDK devuelve un resultado con un subtype de error_max_turns. Una llamada query() de una sola ejecución genera un error que contiene el texto Reached maximum number of turns. El valor predeterminado en ambos casos es sin límite. Si no hay ningún límite configurado y la ejecución sigue deteniéndose, consulta stop_reason en el resultado: max_tokens indica que se alcanzó el límite de salida, y pause_turn indica que el bucle de herramientas del servidor alcanzó su límite de iteraciones y solicita que se envíe la respuesta para poder continuar.

¿Te resultó útil este artículo?