What changes when you move from budget_tokens to effort

Two mechanisms that look like a rename and aren't

On the surface, moving from a numeric thinking-budget field to a named effort level looks like the kind of API change you handle with a quick lookup table — old value maps to new value, done. It isn't, and treating it that way is the single most common way teams under-invest in this specific migration. The two mechanisms aren't the same control renamed; they're genuinely different interfaces to a similar underlying idea, and there's no clean numeric-to-named formula connecting them.

Why there's no conversion table worth trusting

A numeric budget is a hard ceiling — a specific number of tokens the model is permitted to spend thinking, full stop. A named effort level is contextual — the same level can correspond to meaningfully different actual reasoning depth depending on what the specific task looks like, because the model is interpreting "medium" or "high" against the task in front of it rather than being handed a fixed number to spend or not spend. Any conversion table mapping old budget values to new effort levels is asserting a precision that doesn't actually exist underneath it.

The instinct worth keeping, and the one worth discarding

If your old budget settings were tuned conservatively for cost reasons, that instinct is worth carrying forward loosely — lean toward a lower effort tier and test upward from there rather than assuming you need the top of the new range. What's not worth carrying forward is the specific old number itself, or any attempt to derive the "equivalent" new setting mathematically from it. Start from the recommended default and tune against real output, the same way you would if you'd never had a numeric budget in the first place.

What this migration actually reveals about your old settings

For a lot of teams, this migration is the first time in a while that thinking configuration gets genuinely re-examined rather than left as whatever was set once, early on, and never revisited. That's worth treating as an opportunity rather than pure migration overhead — a numeric budget set years ago against a much earlier model generation was very likely never re-tuned as the underlying models changed, and this move is a natural forcing function to actually check whether it was still serving the workload well.

New capability that simply wasn't available under the old mechanism

Beyond parity, the named-level system on current models includes tiers that go beyond anything a numeric budget on an older model offered — including a tier built specifically for the hardest coding and agentic work. Teams migrating purely for compatibility reasons sometimes miss that this is also a genuine opportunity to revisit whether their hardest tasks were being served well by whatever fixed budget they'd been assigned before, since that option simply didn't exist previously.

The testing discipline this migration actually needs

Because there's no formula to trust, the only reliable path through this migration is testing against your real task distribution — not one example, not your easiest case, but a genuine spread including your hardest real tasks — and adjusting the chosen tier based on actual output quality and cost rather than an assumption carried over from the old numeric system.

The organisational side of this migration, not just the technical one

Beyond the request-level changes, this migration is a good moment to actually document why a given effort tier was chosen for a given workload — a decision that, under the old numeric system, often lived only as a single unexplained value in a config file. A named tier with a stated reason behind it ages much better than a bare number ever did, since the next person touching that code has something to actually evaluate the choice against rather than a figure with no context attached to it at all. That documentation habit costs almost nothing to build at migration time and saves real guesswork the next time someone has to decide whether a given setting still makes sense.

See migrating off budget_tokens to the effort parameter for the practical mechanics of this migration, and budget_tokens is not supported on Opus 4.7 and later for the specific error that makes this migration mandatory rather than optional on newer models.