Migrating off budget_tokens to the effort parameter

Two mechanisms doing a similar job, differently

budget_tokens controlled thinking by giving the model a numeric ceiling on how many tokens it could spend reasoning before answering. effort controls the same underlying behaviour through a named level instead of a raw number. They're solving the same problem — how much should the model think before it answers — through genuinely different interfaces, and that difference is exactly why the migration isn't a mechanical find-and-replace.

Why there's no formula from one to the other

It's tempting to look for a conversion — "a budget of this many tokens roughly equals this effort level" — and there isn't a clean one, because the two mechanisms don't map onto each other linearly. A numeric budget is a raw ceiling; an effort level is a qualitative setting that the model interprets contextually against the specific task, which means the same effort level can correspond to meaningfully different actual token spend depending on what's being asked. Treat this as a re-tuning exercise against your real tasks, not a formula to compute once and apply everywhere.

Where to start, and why

Starting from the recommended default — the middle-to-high end of the range, not the bottom — and adjusting from there based on real output quality is a more reliable path than trying to reason out the "correct" starting point analytically from your old budget value. If your old budget_tokens setting was tuned conservatively for cost reasons, that's worth carrying forward as an instinct — lean toward a lower effort level and test upward — but don't treat the old numeric value itself as meaningfully informative about which named level to start at.

Testing across your actual task variety, not one example

A single test case passing at a given effort level tells you very little about whether that level is right across your actual task distribution, especially if your old budget-based setup applied one fixed ceiling uniformly regardless of task difficulty. Test the new effort setting against a representative spread of your real tasks — including the harder end of what you handle — rather than validating against whichever example happened to be convenient to try first.

What you gain that budget_tokens never offered

Beyond parity, effort-based control on newer models unlocks levels that simply didn't exist under the old mechanism — including a tier specifically built for the hardest coding and agentic work. This migration is a genuine opportunity to revisit whether your hardest tasks were actually being served well by whatever fixed budget they were assigned before, not just a compatibility exercise to get through as quickly as possible.

Rebuilding any logic that branched on your old budget values

If your code made decisions based on the numeric budget_tokens value — routing certain task types to a specific budget, or scaling the budget dynamically based on some measure of task complexity — that logic needs to be rebuilt around named effort levels rather than ported as-is, since there's no direct numeric equivalent to map the old scaling logic onto. Treat this as an opportunity to reconsider whether the original scaling logic was well-calibrated in the first place, rather than reconstructing it mechanically against the new parameter just to preserve the old shape of the code.

What to watch for in the weeks after cutover

Effort-level behaviour, unlike a numeric budget, can shift subtly as a model itself is updated over time in ways a hard numeric ceiling never would. Keep an eye on output quality and cost at your chosen effort level for a few weeks after migrating, not just at the point of cutover, since the tuning that looked right on day one is worth reconfirming once real production traffic — not just your test set — has run through it for a while.

See what actually changed from Opus 4.6 to Opus 5 and budget_tokens is not supported on Opus 4.7 and later for where this migration becomes mandatory rather than optional, and the effort & thinking cost estimator for the cost side of choosing where to land.