OpenAI's hosted FT for tool-calling models: what does a JSONL row need beyond text SFT?

Short answer·Medium·4.0 · 0·~3 min·Asked atOpenAI·Relevant atMicrosoft

Attempt it

A team is moving from text-only SFT to OpenAI's hosted fine-tuning API for a tool-calling model (e.g. gpt-5.5-class). They have working multi-turn JSONL but the API rejects half their rows once they add tool calls. Specify the extra fields a tool-aware row needs, both on the assistant turn that issues the call and on the tool response that follows, and explain which field links them. What breaks if the linkage is wrong or missing?

Free · 2 AI evals / day

**Text-only SFT** uses a simple shape. Each turn has a role of user or assistant and a content field carrying free text. The model learns to predict the assistant content given the user content. The moment tool calls enter, the assistant turn changes shape. Instead of free text, it carries a tool_calls array. Each entry in that array has three required pieces: a unique id, a type set to function, and a function object with a name and an arguments field. The arguments field is a JSON string, not a nested object, which catches a lot of teams the first time. The turn right after a tool call uses a brand new role called tool. It does not use user or assistant. The tool turn carries a tool_call_id that matches the id from the assistant call, and a content field with the stringified response from the API. The matching id is the glue. It is the only field that tells the system this returned result belongs to that specific call. If you skip the id or get the match wrong, the API rejects the row before training even starts. If the id is sloppy in a way that still parses, training succeeds but the model learns the wrong association between arguments and results, and you discover the bug only at inference.

**The shape changes in three places.** First, the assistant turn that issues a call replaces free-text content with a tool_calls array. Each entry is an object with three required keys: a unique id (commonly call_<uuid>), a type set to function, and a function object holding name and arguments. The single specification detail that trips most teams up is that arguments is a JSON string, not a nested JSON object. The API rejects rows that nest the object. Second, the immediately following turn uses a new role called tool, not user, not assistant. It carries tool_call_id matching the assistant's id and a content field with the stringified API response. The matching id is the only field that links result to call. Third, the natural-language reply lives on a separate assistant turn that comes after the tool turn. The assistant turn that called the tool should not also carry free-text content. Some validators flag it; the canonical convention is empty content on the call turn and a fresh assistant turn for the reply. Linkage failures come in two flavours. Hard failures: a missing or mismatched tool_call_id causes outright rejection at upload. Soft failures: reusing the same id across rows or across parallel calls in one turn parses fine, but the model learns to ground arguments by ordinal position. At inference, parallel calls get scrambled and results land on the wrong call.

Quick reference

TL;DR

The assistant turn carries a tool_calls array with unique id, type, name, and JSON-string arguments. The next turn uses role tool with a matching tool_call_id, the linkage that survives parallel calls.

Memory aid

Easy to grasp

Picture a busy kitchen where the head chef shouts orders to the prep station. Every order gets its own ticket number stuck to it: order forty-one, two onions diced; order forty-two, one carrot grated. When the prep returns, they staple the chopped food to a matching ticket so the head chef knows what came back from where. If you forget the ticket, or two tickets share a number, the chef ends up putting onions where carrots should go. The hosted fine-tuning API works the same way. Each tool call carries its own ticket, the response carries the same ticket back, and the system uses tickets to keep everything paired even when several orders fly at once.

Key concepts

Tool calling OpenAI API JSONL format Hosted fine-tuning

Detailed answer & concept explanation

~8 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.

Quick scan · 2–4 min

Everything important, quickly.

5 min: assistant turn shape with tool_calls array + the three required keys per call + arguments as a JSON string + tool role and matching tool_call_id + why parallel calls need unique ids + hard versus soft failure modes.

Real-world examples

Real products, models, and research that use this idea.

OpenAI's hosted fine-tuning for gpt-5.5 family enforces this shape exactly and rejects rows at upload when arguments is nested or tool_call_id is missing.
OpenAI's Python SDK ChatCompletion examples emit ids as call_<uuid> and pass arguments as a JSON string, the same convention training data must follow.
Anthropic's tool-use API uses a parallel pattern with tool_use and tool_result blocks, where the tool_use_id field plays the same linkage role as tool_call_id.
Hugging Face's TRL library now ships a chat template for OpenAI-shaped tool-calling JSONL that masks tool turns automatically and validates linkage before training.

Interviewer follow-ups

What an interviewer would ask next. Try answering before peeking at the approach.

QWhy does the OpenAI spec keep arguments as a JSON string rather than a nested object?

QHow would you debug a fine-tune where uploads succeed but at inference parallel tool calls grounded on the wrong results?

QWhat changes if you want to teach parallel tool calls in one assistant turn?

Don't say this

Red flags and common mistakes that signal junior thinking. Click to expand.

Most common mistake

Passing arguments as a nested JSON object instead of a JSON string. The OpenAI spec is strict here, arguments must be a string, and rows that nest the object are rejected at upload time.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

References

Primary sources. Skim if you want the original framing.