GPT-5.5 dropped in the OpenAI API this week — more token-efficient, better at agentic workflows, already live on Vercel's AI Gateway.

But the first line of OpenAI's own migration guide is a warning:

"Treat it as a new model family to tune for, not a drop-in replacement."

That's the part worth paying attention to.

What actually changed

Two variants: gpt-5.5 for agentic coding and multi-step tool workflows; gpt-5.5-pro for demanding multi-pass work where quality beats latency.

More efficient reasoning. Same quality, fewer tokens. Compounds fast in long agent runs.

Reasoning effort defaults to medium. Previously high. OpenAI's advice: start at medium, only push to high if evals show a measurable gain. Higher effort can actually make outputs worse on tasks with weak stopping criteria.

Outcome-first prompts work better. Describe what you want, not how to get there. Skip step-by-step unless the sequence is non-negotiable.

Better tool use. More precise argument selection on large tool surfaces. Fewer hallucinated calls.

The key migration advice

Start clean. OpenAI explicitly says to begin from the smallest prompt that preserves your product contract — don't carry over an old prompt stack and expect it to work.

Every instruction you added to paper over a quirk in the previous model is now debt.

What to do

• Not using it yet? No urgency. gpt-5.4 isn't going anywhere.
• Evaluating? Spin up a fresh system prompt, benchmark against your actual use cases, run ablations.
• On Vercel AI Gateway? Already available: openai/gpt-5.5 or openai/gpt-5.5-pro.
• Running agents? This is where the upgrade is most worth it — efficiency gains and tool use improvements compound on longer runs.

→ Full details in OpenAI's Using GPT-5.5 guide and Prompting Guide.

---

✏️ Drafted with KewBot (AI), edited and approved by Drew.