Claude's tool use limit for this turn

What the tool use limit for this turn means

A tool use limit for this turn means Claude stopped part way through one response because that response ran out of tool calls, not because your account ran out of usage. Everything it found before it stopped is still in the conversation. Send one more message asking it to carry on, and it opens a fresh turn with a fresh budget.

A turn is one round trip inside an agent loop. Claude produces output containing tool calls, the client runs those tools, and the results feed back to Claude for the next decision. That cycle repeats without handing control back to you. The turn ends when Claude produces a response with no tool calls in it. A cap on the turn is a cap on how many of those round trips one answer is allowed to take.

Your plan usage limit is a separate control

The plan limit counts what you have used across a time window. Anthropic's help centre page on error messages, checked on 18 August 2026, lists that one as Approaching 5-hour limit. while you are near it, and 5-hour limit reached - resets [time]. once you cross it. It names a time. Waiting until that time fixes it, and nothing you type in the meantime helps.

The tool use message behaves in the opposite way. It arrives in the middle of a task, and a single follow up message lets the work continue immediately. Your remaining quota is untouched. That is the test to run: if waiting does nothing and continuing works, you were never at your quota. For the quota case, what to do when Claude says the limit is reached lists the options, and how Claude usage limits are counted explains the windows behind them.

Why a turn has a tool budget at all

Every tool call costs context. The call goes out, the tool runs, and the whole result comes back into the conversation. Reading one large file or running one command with long output can use thousands of tokens in a single step, and that text stays in context for the rest of the session. Anthropic's agent loop documentation states the consequence plainly: context accumulates across turns, so a session with many tool calls carries far more than a short one.

A budget on the turn is what stops a loop that is no longer making progress. An agent that searches, reads, searches again and still finds nothing will keep doing that until something interrupts it. The budget is the interruption. It returns control to you at a point where you can redirect the work, which costs much less than letting the loop run to the end of the context window.

Where this limit is visible in the API

Anthropic's public error documentation gives no per turn tool call number for the Claude chat app, so any exact figure you read for it is somebody's guess. The same shape of limit is documented for the API (application programming interface), and that documentation is where the real behaviour is visible.

The stop_reason field on a Messages API response says why generation stopped. The documented values are end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal and model_context_window_exceeded. Two of them describe the situation in this guide.

pause_turn is returned when the server side sampling loop reaches its iteration limit while running server tools such as web search. As of 18 August 2026, the handling stop reasons page gives that default as 10 iterations per request. The documented fix is to send the response back unchanged as the assistant message, so Claude carries on from where it paused. That is the API version of typing "continue" in a chat window.

max_tokens means the response hit the output token ceiling set on the request. If it truncates inside an incomplete tool use block, the tool call cannot be executed, and the documented answer is to retry with a higher max_tokens.

Read the current values on the handling stop reasons page rather than trusting the ones written here. Defaults on that page change, and a stale number is worse than no number.

What makes a chat run out of tool calls

• A question with no natural stopping point. "Find everything written about X" gives the model nothing that tells it the search is finished.
• Repeated reads of the same material, because the answer is not where the model expected it to be.
• Large tool results. One long web page or one big file eats the room the rest of the turn needed.
• Several independent jobs in one message. Each job needs its own tool calls, and they all come out of one budget.
• Connectors and MCP (model context protocol) servers you are not using for this task. Their tool definitions load into the request and give the model more ways to spend the turn.

How to get the answer finished

Reply with "continue", or better, a short instruction naming what is still missing. That opens a new turn with a new budget. The earlier conversation is still in context, so Claude picks up rather than repeating the tool calls it already made.

If it stalls at the same place twice, the task is too wide for one turn, so split it. Instead of asking for a full audit of a repository, ask for the file list first, then ask about one file per message. Four small turns finish work that one large turn cannot.

Narrow what the model has to hunt for. Give the exact file path, or the exact error string, and paste the log in when you already have it. A pasted log costs one message. Making the model go and find that log costs several tool calls, and it may find the wrong one.

Switch off connectors you do not need right now. Every connected tool adds its definition to every request, which consumes context and widens the set of moves the model can choose. The same reasoning applies to a long coding session, where keeping a Claude Code session's context small is the difference between an agent that finishes and one that stops half way.

Set the turn budget yourself when you run an agent

If you drive Claude from your own code, the per turn budget is a setting you own. The Claude Agent SDK (software development kit) exposes max_turns in Python and maxTurns in TypeScript, documented as the maximum number of tool use round trips. The documented default is no limit.

When that cap is reached, the SDK returns a result whose subtype is error_max_turns, and a single shot query() call then raises an error containing the text Reached maximum number of turns. The result still carries num_turns and session_id, so you can resume that same session with a higher limit instead of starting the task again.

From the CLI (command line interface) the same control is a flag, and it applies to print mode only:

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

The flag reference says it exits with an error when the limit is reached, and that there is no limit by default. There is a cost shaped version of the same idea: max_budget_usd in Python and maxBudgetUsd in TypeScript stop the loop at a spend threshold instead of a turn count, and subagent spend counts toward that total. If you run agents on a server you pay for by the month, controlling what an AI agent costs on a VPS is worth setting up before the first long run.

A pause waiting for approval is a different thing. If your agent stops and nothing is spending, read permission_mode rather than the turn count, because a tool is waiting for a human answer that never arrives. Claude Code's auto mode and permission settings covers which modes ask and which run without asking.

How to check the current behaviour yourself

Behaviour here changes without an announcement, so treat every number in this guide as dated rather than fixed. Two places show what is true today.

• The API documentation on stop reasons, which names the server tool iteration default and the way to continue past it.
• Anthropic's help centre page on error messages, which lists the usage limit wording. Checked on 18 August 2026, that page documents the five hour and weekly usage messages and says nothing about a per turn tool cap. That absence is why no official figure for the chat app is quoted here.

Measure your own runs instead. In Claude Code, /context draws current context usage as a coloured grid and points at the tools eating the most of it, and /compact summarises the conversation so far to free space. In the Agent SDK, every result carries num_turns, so you can see how many round trips a typical task really needs before you pick a cap. A number from your own workload is worth more than a number from a forum post.

FAQ

Is the tool use limit the same as my Claude usage limit?

No. The usage limit counts what you have spent across a time window and tells you when it resets, so waiting is the fix. The tool use message stops one response part way through because that response used up its tool calls, and sending another message starts a new turn with a new budget straight away. If continuing works immediately, your quota was never the problem. how Claude usage limits are counted covers the quota case in full.

How do I get Claude to finish a task it stopped part way through?

Send one more message. "Continue" works, and an instruction naming what is still missing works better, because it stops the model rebuilding context it already has. If it stops at the same point a second time, break the task into smaller pieces and give one piece per message. Giving exact file paths, or pasting the content in directly, removes the searching that used up the budget in the first place.

What does "límite de uso de herramientas" or "limite de uso de ferramentas" mean?

These are the Spanish and Portuguese wordings of the same message, usually seen as "límite de uso de herramientas en este turno" or "limite de uso de ferramentas neste turno". The meaning is identical in every language: Claude used up the tool calls allowed inside a single response, and your plan quota is not involved. The fix is the same too. Reply asking it to continue, or split the request into smaller steps. The billing limit is a separate message, and that one names a reset time.

Does upgrading my plan raise the tool use limit for a turn?

Plan level and the per turn tool budget are different controls. Upgrading raises how much you can use over a window, which is the limit that names a reset time. How many tool calls a single response may make is a property of the loop running the model, and Anthropic does not publish that figure for the chat app. Splitting the task into smaller turns is what actually helps, on any plan.

Why does my own agent stop after only a few tool calls?

Check whether you set a cap. The Claude Agent SDK takes max_turns in Python and maxTurns in TypeScript, and the command line interface takes --max-turns in print mode. When one of those is reached, the SDK returns a result with a subtype of error_max_turns and an error containing the text Reached maximum number of turns. The default in both is no limit. If nothing is capped and the run still stops, read stop_reason on the result: max_tokens means the output ceiling was hit, and pause_turn means the server tool loop reached its iteration limit and wants the response sent back so it can continue.