Multi-Turn Tool Calling Explained
Multi-turn tool calling trains a model to produce the next function call given the whole conversation so far, rather than one call per isolated request. Set task: multi-turn-tool-calling-closed-book. It is what you need when a user can say “actually, make that Tuesday”.
What makes tool calling multi-turn?
The input is a conversation, not a request. In single-turn tool calling each example is independent: one user message in, one call out. In multi-turn, the model receives alternating user and assistant turns — optionally with tool result turns carrying what the previous call returned — and predicts the next assistant call in that context.
That changes what the model has to learn. It must resolve references to earlier turns (“cancel that one”), track what has already happened (“you are already in the backup directory”), and notice when the user has changed direction mid-conversation. None of that is inferable from the current message alone.
The task selection guide puts the boundary plainly: single-turn is one-shot function invocation, multi-turn is conversational command sequences.
How does the training data differ?
The whole conversation lives in one messages array per JSONL line, ending with the assistant call the model is trained to produce. The multi-turn data preparation guide documents the rules.
| Aspect | Single-turn | Multi-turn |
|---|---|---|
base.task |
tool-calling-closed-book |
multi-turn-tool-calling-closed-book |
| One JSONL line contains | One user turn, one assistant call | The full conversation |
tool role turns |
Not used | Optional, carry the previous call’s result |
| Target | The single assistant call | The final assistant call in the array |
| Training goal | Map query to function | Understand conversation, then choose function |
Everything else carries over from single-turn: the tools list in job_description.json uses OpenAI function schemas, the emitted arguments is a real JSON object rather than a stringified blob, and each assistant turn contains exactly one call.
One evaluation setting is specific to this task. evaluation.expand_tool_calling_turns defaults to true in the config file, and it expands each test line into several evaluation lines, each ending at a different tool call. A four-call conversation therefore contributes four scored predictions rather than one, which is what you want — it measures every decision point instead of only the last.
Why does per-turn accuracy matter so much?
Because a conversation succeeds only if every turn succeeds, so per-call accuracies multiply. This is the single most important thing to understand about the task, and single-turn benchmark numbers actively mislead people who skip it.
Our FunctionGemma study worked the arithmetic out on base-model scores:
| Task | Base per-call | Implied 2-turn | Implied 5-turn |
|---|---|---|---|
| Smart home control | 38.82% | ~15.1% | ~0.9% |
| Banking voice assistant | 23.35% | ~5.5% | ~0.07% |
| Shell commands (Gorilla) | 9.90% | ~1.0% | ~0.001% |
The same arithmetic runs in your favour after training. At 80% per call a five-turn conversation completes about 33% of the time; at 95% it reaches 77%. The distance between “usually right” and “reliably right” is much larger than the headline numbers suggest, which is why fine-tuning is not optional here. The same 270M model card says as much: it “is intended to be fine-tuned for your specific function-calling task, including multi-turn use cases”.
After fine-tuning, that study’s students reached 90.9% to 96.7% per call, matching or exceeding their 120B teacher.
When is single-turn enough?
When every request is genuinely self-contained. Three tests:
- No anaphora. If users never say “that one”, “the same again”, or “actually”, the conversation history carries no information.
- No state. If the correct call does not depend on what already happened, history is noise.
- One call per session. A command bar or a webhook classifier is single-turn by construction.
Choose single-turn when those hold: the data is simpler to write, and each example is independent so seeds are easier to collect. Choose multi-turn otherwise, and note that training single-turn data will not get you multi-turn behaviour — the model never sees a history field, so it never learns to read one.
Both tasks carry the same model restriction. Students must come from the Qwen3, Qwen3.5, Llama 3, LFM2/LFM2.5, FunctionGemma, or Gemma 4 families, and teachers must be ticked for tool calling in the supported models catalog.
Related terms
Turn expansion is the evaluation behaviour above, controlled by expand_tool_calling_turns. Tool result turn is a tool-role message carrying the output of the preceding call. Orchestrator is the deterministic loop that executes the call and feeds the result back. Related reading: what is tool calling for the single-turn case, FunctionGemma 270M and LFM2.5 350M for the two smallest viable students, and voice assistant command routing for a worked recipe.