Tune reasoning with supported model controls

Learning objective

Configure reasoning per model — prefer adaptive thinking with effort where available, and use manual extended thinking with budget_tokens only where supported — to balance quality, latency, and cost.

Core idea

Reasoning configuration is a model-specific interface. Adaptive thinking lets Claude decide whether and how deeply to reason; output_config.effort steers its spending. Manual extended thinking uses thinking.type: "enabled" with budget_tokens on models that accept that mode. Copying a manual budget into every model request can produce a 400 error rather than more reasoning.

The architect chooses a quality-latency-cost operating point, not a universal “think harder” switch. Compare settings on the same model before adding a second tier. The winning setting must preserve the task’s acceptance criteria, including difficult cases, at the workflow’s deadline and cost.

How it works

Match the configuration to the model

Use the documented configuration matrix rather than inferring support from a family name. The following rows distinguish the models relevant to a migration or selection decision:

The five effort levels are low, medium, high, xhigh, and max. Not every effort-capable model accepts all five. Sonnet 5.5 also accepts thinking.type: "between_tools" at high effort or below to suppress up-front thinking while retaining thinking between tools. That is a narrower control than disabling thinking outright.

Prefer adaptive thinking and effort

A Claude API request can make the intended mode and effort explicit:

{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "Analyze these constraints." }]
}

effort belongs under output_config, not inside thinking. It affects response text, tool calls and arguments, and thinking tokens. It is a behavioral signal, not a numerical token allowance. Lower effort can reduce verification and tool use as well as reasoning length; test the resulting decisions, not merely the shorter reply.

Request-level effort is generally available on supported models across the Claude API, Claude Platform on AWS, Amazon Bedrock, Google Cloud, and Microsoft Foundry without a beta header. Per-message effort is a separate beta capability; this lesson’s request-level example does not require it. Adaptive thinking interleaves with tool use automatically without the manual interleaving beta header.

Adaptive does not mean every turn generates a thinking block. A simple request can receive a direct answer, even at high effort. Increasing effort changes the posture toward reasoning; it does not establish an invariant that a response begins with reasoning.

Keep manual budgets on compatible models

For a Haiku 4.5 integration that still requires manual thinking, the request uses this configuration fragment:

{
  "model": "claude-haiku-4-5-20251001",
  "max_tokens": 8192,
  "thinking": { "type": "enabled", "budget_tokens": 2048 }
}

This is a fragment to combine with the task’s messages. Manual budgets have a 1,024-token minimum and ordinarily must be less than max_tokens, leaving room for the answer. The documented exception permits budget_tokens above max_tokens for supported manual interleaved thinking; Haiku 4.5 does not support interleaved thinking, so on this route budget_tokens must stay below max_tokens.

Manual mode remains useful on compatible models when you need more predictable latency and control over thinking costs than adaptive allocation, at the cost of thinking on every request. Anthropic recommends starting simple tasks near the 1,024-token minimum and complex tasks at 16,000 tokens or more, then adjusting against measured quality and latency. Opus 4.5 also supports output_config.effort alongside budget_tokens: effort shapes the overall response while the budget sets thinking depth.

Manual budget_tokens is a target, not a hard ceiling. max_tokens bounds total output, including thinking and final text. On Opus 4.6 and Sonnet 4.6, migrate away from the deprecated manual mode. On models that reject it, replace it with adaptive thinking and tune effort rather than renaming the budget field.

Measure billed work and completed answers

Thinking tokens are billed as output even when their text is hidden. thinking.display: "omitted" controls display; it does not remove reasoning or its charge. Use usage.output_tokens_details.thinking_tokens to measure billed reasoning tokens, and retain total usage.output_tokens when pricing the response.

Sweep two or three supported effort levels in separate sessions on representative tasks. Anthropic notes that changing request-level effort mid-session invalidates the prompt cache and distorts the comparison. Include answer correctness, completion time, output spend, and tool-use success. A lower max_tokens is a hard truncation control rather than a calibrated saving: it can discard useful work without teaching the model to economize.

Key distinctions and trade-offs

Adaptive versus manual: Adaptive allocates reasoning by request. Manual mode thinks on every request with a configured budget target. A migration changes behavior, not just syntax.

Effort versus maximum output: Effort steers spending; max_tokens stops generation. High effort with too little output room can produce an incomplete result rather than a stronger answer.

Hidden reasoning versus absent reasoning: An empty displayed thinking field does not imply no thinking cost. Judge task outcomes and billed usage rather than visible scratch-work length.

Architecture / decision scenario

A healthcare software vendor generates internal incident analyses without patient identifiers. Its engineering owner requires at least 95% rubric acceptance and a 30-second p95. A prototype copies Haiku 4.5’s enabled configuration into Opus 5.5; the API rejects it. The tempting fix is to remove thinking entirely, but Opus 5.5 rejects disabled too.

The architect switches to adaptive thinking and tests explicit effort. In a hypothetical replay, low reaches 91% acceptance at 12 seconds, medium reaches 96% at 24 seconds, and high reaches 97% at 43 seconds. Medium is the acceptable operating point; high misses the 30-second p95. A separate Haiku 4.5 route retains its supported manual budget until its own migration is evaluated. The owner tracks billed thinking and acceptance together, so hiding summaries cannot masquerade as cost optimization.

Common exam traps

• Sending budget_tokens to a model that rejects manual thinking.
• Assuming Haiku 4.5 and Haiku 5.5 share reasoning controls.
• Putting effort inside thinking or treating it as a strict token cap.
• Treating omitted thinking text as free or disabled reasoning.
• Cutting max_tokens instead of measuring an effort sweep.
• Assuming a beta per-message feature is required for request-level effort.

What to remember

Select the mode from the model’s support matrix. Prefer adaptive thinking with output_config.effort, retain manual budgets only where supported, and measure completed-task quality against latency and billed usage. A supported setting is a candidate for evaluation, not proof that the workload needs it.

Knowledge check

References

• Anthropic, Thinking
• Anthropic, Effort
• Anthropic, Extended thinking
• Anthropic, Steering thinking
• Anthropic, Optimizing for cost and intelligence