What is a tool preamble?
A tool preamble is a short user-facing message a model writes before or between tool calls, restating the goal, outlining the plan and narrating progress, so people can follow a long agent run.
A long agent run can be dozens of tool calls with nothing for a person to read until the end. OpenAI's GPT-5 prompting guide (August 2025) describes tool preambles as brief updates on the upfront plan and progress during tool use, and notes that their frequency, style and content can be steered in the prompt.
Claude often does something similar without being asked. Anthropic's documentation shows Claude often commenting on what it is about to do before a tool call, and says the style can be guided through the system prompt and examples.
What a good preamble covers
The goal, restated
One clear sentence on what the user asked for, before any tools run.
The plan
A short structured outline of the steps the agent intends to take.
Progress
Brief notes as each step or file edit completes, so a reader can see where the run is.
A closing summary
What was actually done, kept separate from the original plan, so differences are visible.
When preambles disappear
In Anthropic's API, forcing a tool with tool_choice set to any or to a named tool prefills the assistant turn, so the model emits no natural language before the tool call even if asked to. To keep the explanation, the documentation suggests leaving tool_choice on auto and asking for the tool in the user message.
Anthropic also advises treating this text like any other model output: phrasing varies, so application code should not parse preambles or rely on their format.
Preambles are not reasoning
A preamble is written for the user. A model's reasoning is a separate, mostly hidden channel. OpenAI's guide recommends the Responses API so reasoning items carry over between tool calls and the model does not rebuild its plan after each one, and reports a rise on Tau-Bench Retail from 73.9% to 78.2% when switching from Chat Completions to the Responses API.
The think tool is different again: a no-op tool that gives the model space to reason mid-run. Preambles inform people; the think tool and reasoning help the model.
Where they go wrong
Noise
A preamble before every small call adds tokens and buries the useful updates. Frequency should match how long the run is.
Claims ahead of evidence
A progress note can say a step worked before its result is checked. Logs and traces, not preambles, are the record of what happened.
How Motiontic's engineers apply it
For agents that people watch, such as support or operations assistants, Motiontic's engineers specify the preamble format in the system prompt and test it in evals alongside correctness. For unattended runs the same notes go to the trace instead of the screen.
Common questions
What are tool preambles in GPT-5?
They are short updates GPT-5 writes around tool calls: restating the goal, outlining a plan, narrating progress and summarising what was done. OpenAI's prompting guide shows how to steer them.
Do tool preambles cost tokens?
Yes, they are ordinary output tokens. For long runs that people watch the cost is usually worth it; for unattended batch work they can be reduced or routed to logs.
Why does Claude skip its explanation when a tool is forced?
With tool_choice set to any or a specific tool, the API prefills the response to force a tool call, so no text comes before it. Using auto with an instruction keeps the explanation.
Related
Agentic eagerness
The dial between an agent that over-explores and one that hands back too soon.
Think tool
A tool that does nothing, so the model has somewhere to stop and think between actions.
Tool calling
How a model asks software to do something: a named tool, typed arguments, a result.
Agent observability
Step-by-step traces of what an agent did, why, and what it cost.
AI product development
New products and major AI features, built from scratch alongside the client's team.
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.