"Claude Reached Its Tool-Use Limit for This Turn"? It's a Pause, Not an Error

The message maps to the API's pause_turn stop reason: a single turn's tool-calling loop hit its iteration cap (10 by default for Anthropic server tools; desktop/CLI clients add their own cap on top). It is NOT a usage limit, NOT a 429 rate limit, and NOT a ban. To resume: in Claude Code or Desktop just click Continue; in your own code, append the paused assistant response and call the API again. To hit it less, scope prompts smaller so a turn finishes inside the cap, and set --max-turns for headless runs.

First: nothing is wrong

You gave Claude a multi-step task, it worked for a while, then it stopped and showed "Claude reached its tool-use limit for this turn" with a Continue button. Click Continue: your context, todo list, and partial work are all intact, and the model resumes exactly where it left off. This is a pause, not an error and not a quota. Under the hood it is the API's pause_turn stop reason, which fires when the tool-calling loop for a single turn hits its iteration ceiling.

Continue does NOT re-run finished work. The completed tool calls are part of the history you send back, so Claude treats them as done and moves forward — it will not repeat searches or edits it already ran.

What's actually happening

A "turn" is one request/response round trip. When Claude calls tools, the runtime loops — call a tool, feed the result back, let Claude decide the next move — until Claude produces a response with no more tool calls. To stop a single turn from running forever, that loop has a hard iteration ceiling. For Anthropic-executed server tools (web_search, web_fetch, code_execution), the documented default is 10 iterations per request; hit it and the turn ends early with stop_reason "pause_turn" instead of "end_turn". On top of that, Claude Desktop and the CLI add their own per-turn cap so one prompt cannot fan out into an unbounded chain of file reads, bash calls, and MCP requests. That client cap is what most people are actually hitting after a long stretch of autonomous work.

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Let me keep digging through the results..." },
    { "type": "server_tool_use", "name": "web_search", "input": { "query": "..." } }
  ],
  "stop_reason": "pause_turn"
}

This is NOT three other things it gets confused with

Read the message before you react

Not a usage / subscription limit

Those lock the session and tell you it resets in N hours. A tool-use pause has a Continue button and loses nothing. If yours says your plan or quota is used up, that is a different problem.

Not a 429 rate_limit_error

A 429 too many requests is a real error class with a retry-after header, caused by calling too fast. pause_turn is an HTTP 200 success that simply paused. Different cause, different fix.

Not "too many MCP tools defined"

That is when 50+ MCP tool definitions bloat the prompt prefix. It is about reducing how many MCP tools you load, a separate lever entirely.

The fix

Resume now, and hit it less often

1. In Claude Code / Desktop: click ContinueThat is the whole fix for interactive use. Continue re-sends the paused conversation, the iteration counter resets for the new turn, and Claude resumes with full context. Nothing to undo, nothing to re-prompt.
2. In your own code: re-send the response as-isHandle pause_turn the way the client does — append Claude's paused response (including the partial server_tool_use block) to your messages array and call the API again. Do not strip it and do not start over. Cap the number of continuations so a runaway loop cannot run up server-tool cost.
3. In headless / SDK runs: set a turn budgetWith claude -p there is no Continue button, so a paused turn can look like the agent quietly stopping. Use --max-turns (and --max-budget-usd) so unattended runs fail loudly at a known ceiling instead of hanging.
4. Scope the prompt so the turn finishes inside the capThe durable fix is to stop asking for work that needs 30 tool calls in one turn. "Audit the auth module" then "audit the data layer" beats "audit the whole repo" — each smaller prompt triggers fewer tool calls per turn and is far less likely to pause.

# Headless: fail loudly at a known ceiling instead of pausing silently
claude -p "Triage the open issues and label each one" \
  --max-turns 40 \
  --max-budget-usd 2.00

Why long autonomous runs pause most

If a workflow that used to run unattended for 45 minutes suddenly starts asking for Continue clicks, you are likely hitting the client-side per-turn cap, which a 2026 change reportedly tightened (one user went from ~60-80 tool calls per turn down to roughly 20). The behavior is the same either way: let the turn resume, or split the work into smaller prompts so each turn stays under the cap. An agent that keeps its context lean per turn also pauses less, because each turn does less work before it is done.

If you want fewer forced pauses

Per-turn tool caps exist to keep a single prompt from running forever, but on long agentic tasks they mean babysitting a Continue button. Wuwei is a free, open-source (MIT) coding agent that runs locally and is model-agnostic. It supports an autonomous smart-continue mode for longer tasks, so multi-step work keeps moving without you clicking Continue on every pause, and you can bring your own Claude key, run a local model, or use free hosted models with no login. It will not remove the underlying API's pause_turn, but it changes who has to click Continue. Download at /en#download.

FAQ

What does "Claude reached its tool-use limit for this turn" mean?

It means the tool-calling loop for that single turn hit its iteration ceiling, so the turn paused (stop_reason pause_turn) instead of finishing. It is not an error, a quota, or a ban. Your work is intact — click Continue and Claude resumes exactly where it left off.

Will clicking Continue repeat work Claude already did?

No. The tool calls Claude already completed are part of the conversation history you send back, so it treats that work as done and moves forward. Continue resumes the task; it does not re-run finished searches or edits.

Is this the same as hitting my usage limit or a rate limit?

No. A usage limit locks the session and talks about resetting in N hours. A 429 rate limit is a real error caused by calling too fast, with a retry-after header. This tool-use pause is an HTTP 200 success that simply paused — different cause, different fix.

How do I stop hitting the tool-use limit?

Scope prompts smaller so each turn finishes inside the cap (split "audit the whole repo" into per-module prompts), set --max-turns for headless runs so they fail loudly rather than pausing silently, and keep each turn's context lean. For long autonomous tasks, an agent with a smart-continue mode resumes pauses for you.

Can I increase the tool-use limit?

For Anthropic server tools the 10-iteration default is set on Anthropic's side, and max_uses only lowers the ceiling (it does not raise it). Desktop and CLI clients have their own per-turn cap. In practice you do not raise the cap — you resume the turn and scope work so each turn stays under it.

"Claude reached its tool-use limit for this turn": what it means and how to fix it