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

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

Un límite de uso de herramientas para este turno significa que Claude se detuvo a mitad de una respuesta porque agotó las llamadas a herramientas permitidas para esa respuesta, no porque su cuenta se haya quedado sin cuota de uso. Todo lo que encontró antes de detenerse sigue en la conversación. Envíe otro mensaje para pedirle que continúe. Así se abrirá un turno nuevo con un presupuesto nuevo.

Un turno es un ciclo de ida y vuelta dentro de un bucle de agente. Claude genera una respuesta que contiene llamadas a herramientas, el cliente ejecuta esas herramientas y los resultados se envían a Claude para que tome la siguiente decisión. El ciclo se repite sin devolverle el control. El turno termina cuando Claude genera una respuesta sin llamadas a herramientas. El límite del turno determina cuántos de esos ciclos puede realizar una respuesta.

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

El límite del plan cuenta lo que has utilizado durante un intervalo de tiempo. La página del centro de ayuda de Anthropic sobre los mensajes de error, consultada el 18 August 2026, indica Approaching 5-hour limit. cuando estás cerca del límite y 5-hour limit reached - resets [time]. cuando lo superas. También especifica una hora. Esperar hasta esa hora resuelve el problema. Nada de lo que escribas mientras tanto ayuda.

El mensaje de uso de herramientas funciona de forma opuesta. Aparece durante una tarea y un solo mensaje de seguimiento permite continuar el trabajo de inmediato. Tu cuota restante no cambia. Esa es la prueba que debes realizar: si esperar no sirve y continuar funciona, nunca habías alcanzado la cuota. 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 cuentan los límites de uso de Claude explica los intervalos que los determinan.

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 es visible este límite en la API

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

El campo stop_reason de una respuesta de la 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 18 de agosto de 2026, la página sobre los motivos de detención del procesamiento establece ese valor predeterminado en 10 iteraciones por solicitud. La solución documentada consiste en enviar la respuesta sin cambios como mensaje del asistente, para que Claude continúe desde el punto en el que se detuvo. Esta es la versión para la API de escribir «continue» en una ventana de chat.

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 una herramienta, la llamada a la herramienta no se puede ejecutar. La respuesta documentada consiste en repetir la solicitud con un valor max_tokens superior.

Consulte los valores actuales en la página sobre los motivos de detención del procesamiento en lugar de confiar en los que aparecen aquí. Los valores predeterminados de esa página cambian, y una cifra obsoleta es peor que no tener ninguna.

Qué hace que un chat agote las llamadas a herramientas

• Una pregunta sin un punto final claro. «Busca todo lo que se haya escrito sobre X» no indica al modelo cuándo ha terminado la búsqueda.
• Lecturas repetidas del mismo material porque la respuesta no está donde el modelo esperaba encontrarla.
• Resultados extensos de las herramientas. Una página web larga o un archivo grande consume el espacio que el resto del turno necesitaba.
• Varias tareas independientes en un mismo mensaje. Cada tarea requiere sus propias llamadas a herramientas y todas consumen el mismo presupuesto.
• Conectores y servidores MCP (model context protocol) que no se utilizan para esta tarea. Sus definiciones de herramientas se cargan en la solicitud y ofrecen al modelo más formas de consumir el turno.

Cómo terminar de obtener la respuesta

Responda con «continue» o, mejor, con una instrucción breve que indique qué falta. Esto abre un turno nuevo con un presupuesto nuevo. La conversación anterior sigue en el contexto, por lo que Claude continúa desde ese punto en lugar de repetir las llamadas a herramientas que ya hizo.

Si se detiene en el mismo punto dos veces, la tarea es demasiado amplia para un solo turno. Divídala. En lugar de pedir una auditoría completa de un repositorio, solicite primero la lista de archivos y después pregunte por un archivo en cada mensaje. Cuatro turnos pequeños permiten terminar un trabajo que un turno grande no puede completar.

Limite lo que el modelo debe buscar. Indique la ruta exacta del archivo o la cadena de error exacta, y pegue el registro si ya lo tiene. Pegar un registro consume un mensaje. Hacer que el modelo busque ese registro requiere varias llamadas a herramientas y puede hacer que encuentre el registro equivocado.

Desactive los conectores que no necesite en ese momento. Cada herramienta conectada añade su definición a cada solicitud, lo que consume contexto y amplía el conjunto de acciones que el modelo puede elegir. El mismo razonamiento se aplica a una sesión de programación larga, en la que mantener reducido el contexto de una sesión de Claude Code marca la diferencia entre un agente que termina y uno que se detiene a mitad del trabajo.

Configura tú mismo el límite de turnos al ejecutar un agente

Si ejecutas Claude desde tu propio código, el límite por turno es una configuración que controlas tú. El Claude Agent SDK (kit de desarrollo de software) expone max_turns en Python y maxTurns en TypeScript. La documentación los define como el número máximo de rondas de uso de herramientas. 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. Una llamada de una sola ejecución a query() genera entonces un error que contiene el texto Reached maximum number of turns. El resultado todavía incluye num_turns y session_id. Por tanto, puedes reanudar la misma sesión con un límite mayor en lugar de iniciar de nuevo la tarea.

Desde la CLI (interfaz de línea de comandos), el mismo control se establece mediante una opción. Sólo se aplica al modo de impresión:

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

La referencia de la opción indica que el comando termina con un error cuando se alcanza el límite y que, de forma predeterminada, no existe ningún límite. Existe una variante del mismo concepto basada en el coste: max_budget_usd en Python y maxBudgetUsd en TypeScript detienen el bucle al alcanzar un umbral de gasto en lugar de un número de turnos. El gasto de los subagentes también cuenta para ese total. Si ejecutas agentes en un servidor cuyo coste pagas mensualmente, configurar cuánto cuesta un agente de IA en un VPS es una medida que conviene aplicar antes de la primera ejecución larga.

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

Cómo comprobar por cuenta propia 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 cuál es la situación actual.

• La documentación de la API sobre los motivos de detención, donde se indica el valor predeterminado de la iteración 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, donde se describe el texto del límite de uso. Comprobada el 18 August 2026, esa página documenta los mensajes de uso de cinco horas y semanales, y no menciona ningún límite de herramientas por turno. Por ese motivo, 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, mientras que /compact resume la conversación hasta ese momento para liberar espacio. En el Agent SDK, cada resultado incluye num_turns, por lo que puede ver cuántos viajes de ida y vuelta necesita realmente una tarea habitual antes de elegir un límite. Un número obtenido de su propia carga de trabajo es más útil 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 ha consumido durante un intervalo de tiempo e indica cuándo se restablece, por lo que 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. Enviar otro mensaje inicia de inmediato un turno nuevo con un presupuesto nuevo. Si la continuación funciona inmediatamente, el problema nunca fue su cuota. cómo se cuentan los límites de uso de Claude explica por completo el caso de la cuota.

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

Envíe un mensaje más. «Continue» funciona, pero una instrucción que indique lo que falta funciona mejor, porque evita que el modelo reconstruya el contexto que ya tiene. Si vuelve a detenerse en el mismo punto, divida la tarea en partes más pequeñas y envíe una parte por mensaje. Proporcionar 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 su plan no interviene. La solución también es la misma. Responda pidiendo que continúe o divida la solicitud en pasos más pequeños. El límite de facturación es un mensaje distinto e 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 distintos. Actualizar el plan aumenta cuánto puede usar durante un intervalo, que es el límite que indica una hora de restablecimiento. La cantidad de llamadas a herramientas que puede hacer 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?

Compruebe si estableció un límite. 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 y 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, lea stop_reason en el resultado. max_tokens significa que se alcanzó el límite de salida. pause_turn significa que el bucle de herramientas del servidor alcanzó su límite de iteraciones y solicita que se envíe la respuesta para poder continuar.