Claude reached its tool-use limit for this turn: what it means

This message means one thing: a single assistant response tried to make more tool calls than one turn allows. It is a per-turn cap on tool calls. It is not your usage limit, not the five-hour session window, and not the weekly cap. Your plan is fine, and you can carry on immediately.

It is not a usage limit

The wording sounds like a quota, which is why it gets confused with billing. It is not. Claude meters subscription usage on a rolling five-hour session window and on weekly caps, and those produce different messages entirely.

The tool-use cap is a structural limit on a single response. It applies per turn, resets the moment a new turn starts, and has nothing to do with your plan, your remaining allocation, or how much you have used this week. If you want to confirm your actual standing, check Settings > Usage or run /usage in Claude Code; you will almost always find plenty of room.

What counts as a tool

A tool is any action beyond generating text. That is broader than most people assume:

• A web search or a page fetch.
• Reading or writing a file.
• Calling a connected service or MCP server, including the exploratory calls made while working out what is available.
• Running code or a shell command.

So a request like "look at every file in this directory and cross-check each one against the docs" is not one action. It is dozens, all inside a single turn, and each one counts.

Why the cap exists

Two reasons, both practical. One prompt that fans out into dozens of calls is expensive to serve, and a runaway loop can consume a great deal on your behalf before anyone notices. Just as importantly, a response that makes very many calls is hard to keep coherent: context fills with intermediate results, early findings get crowded out, and quality degrades in ways that are difficult to see from the outside.

Breaking at a turn boundary is the graceful failure. You get everything done so far, plus a clean point to continue from. The same design is documented on the Claude API, where a response that exhausts the server-side tool loop comes back with a pause_turn stop reason and you continue by sending it straight back; the default there is 10 iterations per request.

What to do right now

Continue. The notice comes with a continue control; using it resumes the work in a new turn with a fresh allowance, and Claude picks up where it stopped. Nothing you already got is lost.

If it fires again on the very next turn, that is the signal that the request itself is shaped wrong rather than merely large. Restructure it instead of continuing over and over.

How to restructure so it stops firing

Five changes, roughly in order of how often they help:

• Split a sprawling ask into staged turns. "Audit the whole repo" becomes "audit the auth module", then "audit the API layer". Each stage finishes cleanly inside one turn.
• Narrow the scope of each turn. Name the directory, the file set, or the specific question. Vague scope is what makes a model explore, and exploration is what burns calls.
• Trim the number of enabled MCP servers. With many servers connected, a meaningful share of calls goes to discovering what is available rather than doing your work. Enable only the few you actually use; see how to add an MCP server to Claude Code.
• Ask for a plan first, then execute it. One turn to produce the plan, later turns to run it. Planning costs almost no tool calls and makes the execution turns far more direct.
• Prefer one broad call over many narrow ones. A single search with a well-built query beats six timid ones, and reading one file whole beats ten partial reads.

The flip side of hitting this

Worth noting briefly: if you are hitting a per-turn tool cap, you are running genuinely agentic work rather than chatting. That usually means a Pro or Max subscription whose weekly surplus resets unused, because weekly capacity is a ceiling and not a balance.

Tokens for Good is one way to spend it: your Claude Code claims a queued nonprofit, researches it against a fixed methodology with citations, and submits a structured report, then stops. It is deliberately scoped to fit inside a run. If long unattended jobs are your pattern, see how long Claude Code can run, or what the approaching weekly limit warning means if you are also seeing that one.

Frequently asked questions