Walk me through what actually happens in a tool-calling loop, and what you do when a tool call fails.
Answer it out loud first, then compare. That's what makes it stick.
The model never runs anything. It proposes a tool call with a name and arguments; my code validates the arguments, runs the tool, and sends back exactly one result for each call id. Then the model decides whether to call another tool or answer. When a tool fails, I return the error as a readable result, not a crash, so the model can correct itself. I cap retries and total steps, and escalate to a human if it keeps failing.
- Model proposes, your code executes
- Validate arguments before touching the backend
- One result per tool call id, then call the model again
- Return errors as results the model can read
- Cap retries and steps, then escalate
A tool-calling loop is a while loop around two kinds of calls: model calls and tool executions. Anthropic's own evaluation guidance describes it the same way: a simple loop that alternates LLM API calls and tool calls.
One turn, step by step
- You send the messages plus tool definitions (name, description, JSON schema).
- The model replies with a text answer or one or more tool_use blocks, each with an id, a name and an input.
- Your code validates the input against the schema, checks permissions, and runs the tool.
- You append a tool_result for each id and call the model again.
- The loop ends when the model answers without a tool call, or when your stop rule fires.
Cost mechanics to mention. Tool definitions are input tokens on every call, and each step resends the history. That is why prompt caching matters: cache reads cost about 0.1x the base input price, writes 1.25x.
When a tool fails
- Bad arguments: reject before execution and return an actionable message ('date must be YYYY-MM-DD, you sent 12/3'). Anthropic recommends error text that tells the agent how to fix the call instead of opaque codes or tracebacks.
- Tool error: MCP's spec says tool errors belong inside the result with isError set, not as protocol errors, because otherwise the model cannot see the failure and self-correct.
- Transient failure (timeout, 429): retry in your code with backoff, not by asking the model.
- Repeated failure: after 2-3 identical failures, stop, record the trace and hand off.
Parallel calls. If the model returns several independent tool_use blocks, run them concurrently and return all results together; this cuts latency.
Close with the guardrail: the model's output is a proposal, so any write passes through a deterministic check in your code.
- The model keeps calling the same failing tool. What do you do?
- Which tool errors should the model see, and which should your code swallow?
- How do parallel tool calls change your loop?
- Tool Use and MCP for LLM Applications - DataInterview FDE course (prep, 2026-10-12) Says wiring a model to systems and answering 'what happens when the tool fails?' is core to reported agent-over-tools rounds.
- Writing effective tools for AI agents - Anthropic (official, 2025-09-11) Describes the simple while-loop around LLM and tool calls and advises actionable error messages.
- Schema Reference - Model Context Protocol (docs, 2026-07-28) Tool errors should be reported in the result with isError true so the model can see and self-correct.
- Pricing - Claude Platform Docs (docs, unknown) Cache read is 0.1x base input price on most models; 5-minute cache write is 1.25x.