TL;DR
Giving the model a tool means calling it more than once. The cycle is: model decides → platform runs the tool → result goes back to the model → model decides again, repeating until the model answers with no further tool calls. When a tool fails, hand the failure back as a readable result so the model can recover — don't crash the run.
The idea
A single model call isn't enough once tools are involved, because a tool call produces a result the model still needs to read. So the agent runs a loop:
- Model reads the prompt and available tools, and decides: answer, or call a tool?
- Platform runs the chosen tool with the model's arguments and captures the result.
- Model sees the result appended to the conversation, and decides again: answer now, or call another tool?
- Repeat from step 2 until the model produces a final answer with no tool calls.
The model and the platform pass control back and forth — tool call out, result in — until the model stops calling tools.
What stops the loop
Two independent mechanisms keep the loop from spinning forever:
- The model's own stopping point. The model is allowed to choose not to call another tool. When it has what it needs, it just writes the answer — and the loop ends naturally. This is the normal exit.
- A hard max-iterations cap. The platform sets a ceiling (say, 10 cycles) as a safety net for the unhappy path — a confused model that keeps calling tools, or two tools that bounce work back and forth. The cap guarantees termination even when the model's own judgment doesn't.
Most queries finish in 1–3 cycles. The cap exists for the rare run that doesn't.
Analogy
It's a back-and-forth conversation between the model and your code: "run this for me" → "here's the result" → "okay, now run this" → "here it is" → "great, here's the answer." The cap is the meeting organizer who says "we've gone around enough times — let's wrap up."
When a tool fails
Tools touch the real world, so they fail: a network timeout, a record that doesn't exist, an argument that doesn't validate. The model only ever knows what you put in the tool result — so what you do with a failure decides whether the agent recovers:
| Approach | What the model sees | Result |
|---|---|---|
| Throw / crash the run | Nothing — the loop dies | User gets an error page; no recovery |
| Return a clear error result | "No account found for that email" | Model apologizes, asks for the order ID, or tries another tool |
| Return a raw stack trace | A wall of internal detail | Model may leak it or get confused |
Returning a clear, short error string as the tool result keeps the loop going. The model reads "no account found for that email" the same way it reads a success — as information — and adapts: ask the user for more detail, try another tool, or explain what went wrong. Throwing an exception instead ends the run before the model ever gets to react.
Try it yourself
Step through a real M2 lab trace: the model thinks, calls lookup_account,
receives a result, then writes the final answer. Click Next step to walk the
loop one move at a time and watch control pass between the model and the platform.
Common mistake
Assuming the loop is "the model doing everything." It isn't — your code runs every tool and feeds the result back. So when a tool breaks, don't dump the raw exception or a giant payload into the result: it bloats the context on every remaining cycle and can leak internal details into the answer. Catch the failure, translate it into a brief, model-readable message, and return that.
Key takeaways
Key takeaways
- The tool loop is model → tool → model, repeating until no more tool calls.
- The model's natural exit is choosing not to call another tool.
- A max-iterations cap is the safety net that guarantees termination.
- When a tool fails, return a clear, short error result so the model can recover — don't throw, and don't dump raw detail.
Go deeper: the conversation grows every cycle
Each trip through the loop appends to the conversation: the model's tool call, then your tool result, then the model's next move. Because LLMs are stateless (Module 1), the entire growing thread is re-sent on every cycle.
That has two consequences worth remembering:
- Cost climbs with loop length. A 5-cycle run re-sends a longer history each time, so tool-heavy agents cost more than single-shot calls — something you'll measure directly in the Traces module.
- Tool results are context too. A tool that dumps a 50 KB blob into the result bloats every subsequent turn — and a clear one-line error is far cheaper than a stack trace. Return the smallest result that answers the question.
The loop is simple; its cost is cumulative. Keep cycles few and results lean.