GPT-5.5 prompting guide
Summary
GPT-5.5 is now available via API, requiring a new approach to prompt engineering and model migration. Developers should treat this release as a distinct model family rather than a drop-in replacement for GPT-5.2 or GPT-5.4.
Key Points
- GPT-5.5 requires a new prompting baseline; developers should avoid carrying over instruction stacks from GPT-5.2 or GPT-5.4.
- For multi-step tasks with high latency, implement a short (1-2 sentence) user-visible update acknowledging the request and stating the first step before initiating tool calls.
- Optimization should focus on tuning reasoning effort, verbosity, tool descriptions, and output format against representative examples.
- The
openai-docsskill in Codex supports automated project migration via the command:$openai-docs migrate this project to gpt-5.5.
Technical Details
To mitigate the perception of system failure during long-running tasks, applications should be configured to send an intermediate acknowledgment. Before the model begins multi-step tool calls, the system should output a brief, one-to-two-sentence update that confirms the request and identifies the first step of the process. This is particularly effective for managing user expectations during periods of high reasoning latency.
Migration strategies should prioritize establishing a new baseline using the smallest possible prompt that preserves the existing product contract. Once this baseline is established, developers should iteratively tune the model's reasoning effort, verbosity, and tool descriptions. Relying on prompts optimized for previous versions may result in suboptimal performance due to the architectural differences in the GPT-5.5 model family.
Impact / Why It Matters
Developers must prepare for a significant refactoring of existing prompt architectures to ensure compatibility and performance. Treating GPT-5.5 as a new model family is essential to avoid the inefficiencies of legacy prompt stacks.