A safe multi-step tool-use agent loop with the Claude API

TL;DR

Run the agentic loop without letting it run away. Set termination rules before the first call. Each tool result goes back as a toolresult block referencing the tooluse id. Keep results compact: huge raw outputs eat the window and the budget.

When to use

You are seeing this: Know which tools you execute. Use this skill when you run into "A safe multi-step tool-use agent loop with the Claude API".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Run the agentic loop without letting it run away.

1. Know which tools you execute. Client tools are defined by you and executed by your application: the model returns a structured call, your code runs it, you send back the result. Server tools (like web search) are executed by Anthropic and return results in the same response. Do not build an execution harness for a server tool.
2. Write tool descriptions that trigger. The model decides when to call a tool from the tool's description. Name the exact situations that warrant the call, the required parameters, and what the tool returns. A vague description is the number one reason a tool never fires; test the description with natural phrasing, not just the happy path.
3. Set termination rules before the first call. Cap total iterations, total tokens, and wall-clock time. Define what "done" looks like (final answer with no tool calls, or a specific result) and stop the loop the moment it is reached. An uncapped loop ends at the budget cap, not at success.
4. Feed results back in the right shape. Each tool result goes back as a toolresult block referencing the tooluse id. Keep results compact: huge raw outputs eat the window and the budget. Summarize or truncate with the essential fields first.
5. Handle the model that will not stop calling tools. If the loop keeps calling tools without converging, that is a prompt problem, not a loop problem: the task is underspecified or the tools do not cover what the task needs. Stop, clarify the instructions or add the missing tool, then restart the task.
6. Guard the loop with evals. Record transcripts of loop runs and grade them: did it call the right tools in the right order, did it stop at the right time, did it stay in budget. Cheap graders (toolused, toolorder) catch most loop regressions without a judge model.

Claims verified against Anthropic's official docs (platform.claude.com) on 2026-09-26. Evidence URLs in public_references.