The `effort` Parameter: Why budget_tokens Is Being Retired

The prior concept in this task statement describes Extended Thinking as a lever configured with thinking: {type: "enabled", budget_tokens: N} -- a fixed token ceiling you hand-pick per request. That configuration shape is not the end state of the API; it is a transitional mechanism that newer model generations are actively moving away from, and an architect who only knows the budget_tokens shape will eventually write code that breaks outright against a newer model, not just code that performs sub-optimally.

Two Generations, Two Different Knobs

Older model generations configure thinking depth with a hard token budget you set in advance: you guess how many tokens the model will need to reason through a task, and you're either right (the budget covers it) or wrong (the model truncates mid-thought, or you overpaid for headroom it didn't use). Newer model generations replace that guess with a qualitative effort parameter -- you tell the model roughly how much depth the task deserves (using levels such as low, medium, and high), and the model manages its own token spend within that qualitative envelope rather than you pre-committing a number.

This is a meaningful design shift, not just a renamed field: `budget_tokens asks the architect to predict token consumption in advance, which is exactly the kind of guess that's hard to get right across a diverse workload; effort` asks the architect to state how much the task matters, which is a judgment the architect is actually well-positioned to make, and lets the model translate that judgment into whatever token spend the specific input requires.

The Deprecation Timeline an Architect Must Track

`budget_tokens is being phased out generation by generation, and the practical consequence for a production system is sharp rather than gradual: on the generation where it's deprecated, it still works (with a warning you'd only see if you were watching for it); on the generation after that, passing budget_tokens returns an outright 400-class error and the request fails. This means a system that pins an older model version specifically to keep budget_tokens` working (a reasonable short-term choice) is accumulating technical debt that becomes a hard migration requirement the moment that version is retired -- not a nice-to-have refactor you can defer indefinitely.

Practical Guidance for the Architect

1. Treat effort as the parameter to design new systems around, and `budget_tokens` as a legacy shape you only keep because you're pinned to an older model version for a documented reason (see the model-version-pinning discipline in the prior concept).
2. Know which parameter belongs to which generation before touching a model-upgrade ticket. The single most avoidable production incident in this area is exactly the one this concept exists to prevent: an architect upgrades a pinned model version as part of routine maintenance, doesn't realize the newer generation has moved past `budget_tokens`, and ships a request shape that the new model rejects outright -- turning a routine version bump into an unplanned outage.
3. When migrating a mixed-model pipeline (per the mixed-model-pipeline concept earlier in this task statement), audit each step's thinking configuration independently -- a pipeline can easily have some steps on newer models that expect effort and other steps on older, still-supported models that still expect `budget_tokens`. Treating "our thinking configuration" as one system-wide setting is the same mistake as treating "our model" as one system-wide choice.

Illustrative Shape (Conceptual, Not a Specific SDK Version)

The exact accepted effort-level strings and the exact generation boundaries where each shape stops working are the kind of detail that shifts as Anthropic ships new model generations -- always verify the current accepted parameter shape against the live API documentation before finalizing a request builder, rather than hard-coding either shape from memory.