beckon
Beckon blog

Claude Tool Calls Explained: Who Runs Them and How Claude Code Loops

ยท Beau Johnson

In shortAn agent is a model calling tools in a loop: the app sends the conversation, the model answers or requests a tool, the app runs it and sends the result back, and the loop continues while stop_reason is tool_use. In my Claude Code run that took 14 requests and 16 tool calls, and the tools only ran for about 4 of the 120 seconds.

I gave Claude Code one prompt and logged every step of the agent loop. Two minutes later it had made 16 tool calls, built a new feature and gotten every test passing, but the tools themselves ran for only about four seconds of that. In this video I break that real run down one step at a time. It's for developers who use AI coding agents and want to know what's actually going on between the prompt and the final answer.

What I cover in this video

  • 0:00 One prompt, 16 tool calls, and why the tools only took about 4 seconds
  • 0:45 The agent loop in one picture, and the single field that keeps it going
  • 2:16 Tool calls are the model's only hands, and which tools my agent actually used
  • 3:50 How tool results land back in context, and how Claude Code truncates them
  • 5:24 Why agents stop too early or never stop
  • 7:41 Errors and recovery: five failures, none flagged as an error
  • 9:12 Context growth turn by turn, and why caching matters
  • 9:57 Watching agents work live in Beckon

The loop, and the one field that runs it

Anthropic's definition of an agent is simple: a model using tools based on feedback from its environment, in a loop. The idea goes back further than most people think. In October 2022 the ReAct paper described it as thought, action, observation, repeated.

Here's the loop in four steps:

  1. The app sends the model your prompt, the system prompt and a list of tools.
  2. The model replies with either a final answer or a request to use a tool.
  3. If it asked for a tool, the app runs it.
  4. The result is added to the conversation and the whole thing goes back to the model. Repeat.

Whether it keeps going comes down to one field, stop_reason. If it says tool_use, the loop goes around again. Otherwise it's done. Anthropic's docs literally call it a while loop keyed on stop_reason, and OpenAI describes the same loop for Codex. In my run (Claude Code on Opus 5.5) it went around 14 times: 14 model requests, 16 tool calls, one final answer. Claude Code normally writes every message, tool call and result to a plain text file on your machine. For this run I saved the full live log myself, and that's what I counted from.

Tool calls and how results come back

The model can't run anything or touch a file. All it can do is write text. A tool call is just the model writing a structured request (a tool name plus inputs), and the app runs it. As Anthropic explains, the model never sees how a tool is built. It only gets the tool's schema and whatever result you send back.

Of my 16 calls, 12 were Bash, 3 were Write and 1 was Edit. There wasn't a single Read call. It ran cat in the shell to look at files even though a Read tool was available. A few gotchas: each Bash call is a fresh process, so an environment variable you export in one command is gone by the next. Edit uses exact string matching, so if the indentation is off by one space, the edit misses.

The results surprised me. In Claude's API a tool result goes back inside a user message, so your terminal output sits in the same slot as you typing to the model, and it has to come right after the tool call. Claude Code also doesn't pass everything along:

  • A passing command returns up to about 30,000 characters of output.
  • A failing command returns about 10,000, cut from the top and the bottom, so the middle of a huge error log gets dropped.
  • A Read call is capped at 25,000 tokens.

In call two, the agent printed every source and test file at once, almost 20,000 characters, and the next request was almost 10,000 tokens bigger. After that it piped most commands through tail or grep so it only read the lines it needed, which is what you want. Empty output is a problem of its own. The SWE-agent team added a message saying the command ran successfully and produced no output, and Claude Code does the same. Two of my calls came back with just that.

Why agents stop, and what good recovery looks like

The model decides when to stop. The loop ends the moment it writes a response with no tool call in it, and by default nothing else steps in. Claude's API has seven stop reasons: end turn, max tokens, stop sequence, tool use, pause turn, refusal and running out of context window. Only tool_use means "run a tool and come back." Hard limits are opt-in. Claude Code's max turns flag only works in print mode and has no limit by default, and the same goes for the Agent SDK. One trap: count the final answer as a turn, or the run ends with an error and no final answer.

METR looked by hand at a small set of failed runs. With the November 2023 GPT-4, 12 of 31 failures came from repeating an action that had already failed. With o1, 16 of 32 came from giving up too early. METR notes that o1 may have gotten harder tasks. Anthropic has also said Claude would sometimes see that progress had been made and declare the job done.

A good stop is honest. In a second run I asked Opus only to add type checking and said every test had to pass, but eight tests were for a feature that didn't exist yet. It told me the type check passes, eight tests still fail, and those eight were failing before it changed anything. It didn't fake a pass and it didn't build a feature I hadn't asked for. If you want to keep an agent working, Claude Code has a stop hook that can block the stop. If the hook blocks eight times in a row with no tool run in between, though, Claude Code ends the turn anyway. The newer /goal command is basically that idea, with a fresh model checking your goal after every turn.

On errors, the API has an is_error flag, but Anthropic's advice is mostly about the message: say what went wrong and what to try next. In my run, five results showed a failure: 37 type errors on the first strict check, 8 failing tests, and then 2 new errors the agent caused itself. None was flagged as an error, because it piped its checks through tail and grep. To Claude Code, every command worked and the output was just text. The model read it and fixed the problems, and one sed command later everything was green.

Recovery matters. The SWE-agent paper found any edit attempt had a 90.5% chance of eventually working, but after one failed edit that fell to 57.2% (older models, but the point still holds). Good recovery means changing the plan instead of retrying the same thing. METR has an example of Claude 3.5 Sonnet failing at sed edits until it switched to rewriting the whole file. This is also why Anthropic recommends giving agents more feedback, like a type checker or linter.

Context grows every turn

Each time around, the whole conversation is sent again: system prompt, tools, your prompt, every tool call and every result. Before running a single command, my context was already at about 30,000 tokens, counting the system prompt, tool definitions, my installed connectors and skills, and the prompt. The last request was about 57,000. Across all 14 requests the model read about 650,000 tokens for a two-minute job.

OpenAI's Codex write-up asks whether the agent loop is quadratic, and the answer is yes. Prompt caching is what saves it, because each request starts with the exact same text as the last one. Most of my 650,000 tokens came from the cache. OpenAI notes the cache breaks if you change the tools, the model or the sandbox mid-conversation. And more context still isn't free. Anthropic calls it context rot: the more tokens in the window, the worse the model gets at recalling what's in there. Keep tool output short, point the agent at file paths instead of dumping whole files, and keep your tool list lean, since every loaded tool rides along on every turn. (I go deeper on that cost in MCP vs CLI for coding agents.)

Unless you scroll back through a terminal, you never see any of this. In Beckon, every agent pane shows a live read of what that agent is working on, right in the header next to its badge. When an agent needs me its pane glows, and I can press a key and ask what the agents are doing.

Key takeaways

  • The agent loop is a while loop on stop_reason. Only tool_use sends it around again.
  • Most of a run is the model thinking, not tools running: about 4 seconds of tool time in a 2-minute run.
  • Claude Code truncates tool output (about 30,000 characters on success, about 10,000 on failure), so filtered, targeted commands work better.
  • Piped commands can hide failures from the is_error flag. The model still reads the text and can recover from it.
  • Context is resent every turn. Caching keeps the cost down, but lean tools and short output still matter.

FAQ

How does Claude Code decide when to stop?

The model decides. The loop ends as soon as it writes a response without a tool call. Only the tool_use stop reason sends the loop around again, and by default nothing else steps in.

Does Claude Code have a max turns limit by default?

No. The max turns flag only works in print mode and has no limit unless you set one, and the Agent SDK works the same way. Count the final answer as a turn, or the run ends with an error and no final answer.

How much tool output does Claude Code send back to the model?

Up to about 30,000 characters for a passing command and about 10,000 for a failing one, cut from the top and the bottom. A Read call is capped at 25,000 tokens.

Why does the context window grow so fast in an agent loop?

The whole conversation, including every tool call and result, is sent again on every turn. In my run that went from about 30,000 tokens to about 57,000, with about 650,000 tokens read in total, mostly from the cache.

Run your agents in Beckon

A workspace for your coding agents. Get more work done in less time.

Download BeckonSubscribe on YouTube
Full video transcript

0:00I gave Claude Code one prompt and two minutes later, it had made 16 tool calls, built a new feature, and every single test was passing. But here's what got me. Out of those 2 minutes, the tools only ran for about 4 seconds. The rest was the model, reading, deciding, and writing the next step. So, in this video, I'm breaking down the agent loop one step at a time using that real run. what the loop actually is, how a tool call works, how the results get back in, why agents stop too early or never stop, what a good agent does after a failed command, and how the context grows every single turn. Let's jump right into it. So, what is an agent exactly? Anthropic's own definition is pretty

0:45simple. An agent is just a model using tools based on feedback from its environment in a loop. That's it. And this idea is older than most people think. Back in October of 2022, a paper called React described it as thought, action, observation over and over. Here's how the loop actually works. And don't get lost in the sauce here. It's super simple. Step one, the app you're using sends the model your prompt, the system prompt, and a list of tools. Step two, the model writes back one of two things, a final answer or a request to use a tool. Step three, if it asks for a tool, the app runs it. And step four, the result gets added to the conversation and the whole thing gets sent back to the model. Then it repeats.

1:30And here's something most people don't think about. The thing that decides whether the loop keeps going is one field. It's called stop reason. If the stop reason says tool use, the loop goes around again. If it doesn't, you're done. Anthropic's own docs literally call it a while loop keyed on stop reason. And OpenAI describes the same loop for codeex. Two rival labs, same loop. So in my run, that loop went around 14 times. 14 requests to the model, 16 tool calls, one final answer. And you can go back and look at all of it. Normally Claude Code writes every message, every tool call, and every result to a plain text file on your machine. For this run, I saved the whole live log myself, and that's how I counted all of this. So let's freeze it

2:16and look at each piece. Still juggling cloud code, codecs, and cursor in five terminal windows. Beckin puts every coding agent on one canvas side by side. Press a key and just talk to them. Every idea gets its own workspace with memory that carries over. Becken. Hey, Beckin.ai. So, first the hands. The model can't run anything. It can't touch a file. All it can do is write text. A tool call is just the model writing a structured request. a tool name plus the inputs and the app runs it. We'll keep that part quick, but Anthropic says it really clearly. The model never sees how the tool is built. It only gets the tools schema and the result you send back. So, what did my agent actually use? 12 of the 16 calls were bash, three were

3:03write, and one was edit. And not one read call. It just ran cat in the shell to look at the files, which is pretty interesting because it had a read tool sitting right there. These models are so used to a terminal that the shell is kind of their default. Here's something to pay attention to, though. Each bash call is a fresh process. So, an environment variable you export in one command is gone by the next one. And edit is exact string matching. One space off in the indentation and the edit misses. And all of that has a cost before anything even happens. On the very first request, before it ran a single command, my context was already at about 30,000 tokens. That's the system prompt, the tool definitions, all the connectors and skills I have installed, and the prompt itself. So,

3:50yours could be bigger or smaller. So, the agent runs a command. Where does the output go? This one surprised me. In Claude's API, a tool result goes back inside a user message. So, from the model side, your terminal output shows up in the same slot as you typing to it. And it has to come right after the tool call. Nothing in between. And Claude code doesn't hand the model everything either. If a command works, the model gets up to about 30,000 characters of output. If the command fails, it only gets about 10,000 as a cut from the top and the bottom. So, a giant error log gets chopped in the middle. And a read call is capped at 25,000 tokens. You can see this happen in my run. Call number two. The agent printed every source file and every test file in one go. That was

4:37almost 20,000 characters. And the next request to the model was almost 10,000 tokens bigger, one call. But then watch what it does next. A lot of its commands after that go through tail or GP, so it only reads the lines it needs, like the pass and fail counts from the tests, which is exactly what you'd want it to do. An empty output is a problem, too. The SWE agent team added a message that literally says, "Your command ran successfully and did not produce any output," just so the model isn't left staring at nothing. And claude code does the same thing. In my run, two calls came back with just bash completed with no output. So how does it know when to stop? The model decides. The loop ends the moment the model writes a response with no tool call in it. That's it.

5:24There's no referee by default. Right now there are seven stop reasons in Claude's API. End turn, max tokens, stop sequence, tool use, pause turn, refusal, and running out of context window. And only one of them means run a tool and come back. Tool use. And the hard limits are something you turn on yourself. Claude Code's max turns flag only works in print mode. And there's no limit by default. Same with the agent SDK. And here's a little trap. You have to count the final answer as a turn, too. If you don't, the run ends with an error and no final answer. So why do agents quit early or never stop? MER looked at this by hand on a small set of failed runs. With the November 2023 version of GPT4,

6:0912 of 31 failures were the model repeating an action that had already failed. With 01, 16 of 32 were the model just giving up too early. So in that sample, the older model kept looping and the newer one quit early. MER says that could be because 01 got harder tasks. So take that for what you will. And Anthropic has said Claude would sometimes look around, see that progress had been made, and declare the job done. Now, a good stop looks like this. In a second run, I only asked Opus to add the type checking, and I said every test had to pass. But eight of those tests were for a feature that didn't exist yet. So, it finished and told me straight up, the type check passes, but eight tests still fail. And those eight were failing before I touched anything. That's a good

6:56stop. It didn't fake it, and it didn't go build a feature I never asked for. And if you want to keep it from stopping, Claude Code has a stop hook that can block the stop and send it back to work. But if your hook blocks eight times in a row without Claude running a single tool in between, Claude Code overrides it and ends the turn anyway. And the newer/goal command is basically that with a fresh model checking your goal after every turn. So what happens when a command fails? In the API, there's one little flag on the result called is error. But Anthropics advice is really about the message, not the flag. Don't just say failed. Say what went wrong and what to try next. But here's what I saw in my own run. Five results showed a failure. The first

7:41strict type check printed 37 errors. The test run showed eight failing tests. And after the agent rewrote a file, the type check came back with two brand new errors that it caused itself. And none of those five came back flagged as an error. That's because it piped its checks through tail and GP. So, as far as Claude code could tell, every command worked. It was all just text. The model read it like anything else and it fixed it. Those two new errors, one said command and everything was green. And recovery matters more than you'd think. The SWE agent paper found that any edit attempt had a 90.5% chance of eventually working, but after one failed edit, that dropped to 57.2%. That's older models, but the idea still

8:27holds. Errors stack up. So what does good recovery look like? Basically, it changes the plan instead of trying the same thing again. Metr has an example where an older claude 3.5 sonnet kept failing with said edits and it finally switched to just writing the whole file from scratch. And this is why Anthropic says to give your agent more feedback, like a type checker or a llinter, which is literally what I asked for in this run. And you can see it working on its own errors. Now, let's talk about the part that adds up fast. Context. Every time the loop goes around, the whole conversation gets sent again. The system prompt, the tools, your prompt, every tool call, and every result. You can see it in my run. 30,000 tokens on the first

9:12request, 57,000 on the last. And if you add up what the model read across all 14 requests, it's about 650,000 tokens for a 2minute job. And OpenAI said this out loud in their codeex writeup. They ask, "Isn't the agent loop quadratic?" And they answer, and you would be right. The thing that saves it is prompt caching. Each new request starts with the exact same text as the last one, so it can be cached. And in my run, most of those 650,000 tokens came out of the cache. But OpenAI says that cache breaks if you change the tools, the model, or the sandbox in the middle of a conversation. And even with caching, more context isn't free. Anthropic calls it context rot. The more tokens in the window, the worse the

9:57model gets at recalling what's in there. So keep tool output short, point the agent at file paths instead of dumping whole files, and keep your tool list lean. Like I said, every tool that's loaded rides along on every single turn. So that's the loop. 14 trips, 16 tool calls, and you'd never see any of it unless you scroll through a terminal. That's why I like having it right in front of me. In Beckin, every agent's pane has a live read of what that agent is working on, right in the header next to its badge. When one needs me, it glows, and I can press a key and just ask what the agents are doing. So, when I've got three of them running, I'm not guessing which one needs me. So, what's the longest you've let an agent run before you checked on it? 10 minutes, an

10:43hour. Put your record under this video. And if you can picture the loop now, one turn at a time. A thumbs up on this one tells me to make more like it. Have a blessed day.