Thinking and Effort
Current Claude models decide for themselves when and how much to think. You steer that with the effort level, cap total output with max_tokens, and choose whether the thinking summary is returned with display. Per-model rules differ, so check the table in the docs for your model.
When to Use
- Multi-step reasoning: math, debugging, planning, code generation
- Agent loops where the model should evaluate tool results before acting
- Migrating code written for fixed
budget_tokensthinking - A request returns 400 on its
thinkingfield, or answers are truncated
Workflow
Step 1: Look up your model's thinking modes
The thinking documentation has a per-model table that shows what each model does with no thinking field, adaptive, enabled with budget_tokens, and disabled. As documented at the time of writing:
- On the newest models, thinking is on by default and
budget_tokensis rejected (400); some rejectdisabledtoo - On some previous-generation models, thinking is off until you send
thinking: { type: "adaptive" } - Older models support only the legacy manual mode:
{ type: "enabled", budget_tokens: N }
Do not copy a thinking object between models without checking that table.
Step 2: Turn thinking on and choose what you see
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const MODEL = process.env.ANTHROPIC_MODEL!; // a current model ID
const response = await client.messages.create({
model: MODEL,
max_tokens: 16000,
thinking: { type: "adaptive", display: "summarized" },
messages: [{ role: "user", content: "Find the bug in this function and explain it: ..." }],
});
for (const block of response.content) {
if (block.type === "thinking") console.log("[summary]", block.thinking);
if (block.type === "text") console.log(block.text);
}
display values:
| Value | Returns | Typical use |
|---|---|---|
"summarized" |
A readable summary of the reasoning | Showing reasoning to users or debugging |
"omitted" |
Thinking blocks with an empty thinking field and a signature |
Production paths that never show reasoning; text starts streaming sooner |
The default differs by model ("omitted" on many newer models), which is why code that printed thinking can suddenly print nothing. No setting returns the raw chain of thought, and billing is the same either way.
Step 3: Set effort
Effort lives in output_config, not inside thinking:
const response = await client.messages.create({
model: MODEL,
max_tokens: 16000,
output_config: { effort: "medium" }, // low | medium | high | xhigh | max (availability varies by model)
messages,
});
Effort is soft guidance on how readily and how deeply Claude thinks (and how much it writes). The default level differs by model, so set it explicitly when behavior matters. Start at the level your workload needs on a sample of real requests and move one step at a time; a lower level is usually the first lever when responses are slower or more expensive than needed. Prompt guidance ("think carefully" or "answer directly") can shift behavior further, but measure it, because wording sensitivity is real.
Step 4: Handle tool use correctly
Thinking interleaves with tool calls automatically on models with adaptive thinking (older models needed a beta header for interleaving). When you return tool results, include the assistant's thinking blocks unmodified, including the signature. Modified thinking blocks are rejected.
messages.push({ role: "assistant", content: response.content }); // keep every block as returned
messages.push({ role: "user", content: toolResults });
Not every assistant turn will start with a thinking block: with adaptive thinking the model can skip thinking on simple steps. Do not write code that assumes one is present.
Step 5: Control cost and truncation
max_tokensis a hard cap on thinking plus text for that request. If you seestop_reason: "max_tokens", raisemax_tokensor lower effort- Thinking tokens are billed as output tokens. Read
usage.output_tokens_details.thinking_tokensto see how much ofoutput_tokenswas reasoning - With large
max_tokens, stream the request (the SDKs expect streaming for very long generations)
Step 6: Keep settings stable within a conversation
The resolved effort value and thinking configuration are part of the prompt. Changing them between requests invalidates cache breakpoints after the system prompt on many models. Pick one configuration per conversation; for per-turn variation, the docs describe per-message steering and (on some models, beta) per-message effort changes that preserve the cache.
Migrating From budget_tokens
| Old code | New approach |
|---|---|
thinking: { type: "enabled", budget_tokens: 8000 } |
thinking: { type: "adaptive" } (or omit where thinking is on by default) plus output_config.effort |
| Tuning the budget to control depth | Tune effort; cap total output with max_tokens |
| Expecting visible thinking text | Set display: "summarized" explicitly |
| Interleaved-thinking beta header | Not needed with adaptive thinking |
Check the migration guide for model-specific breaking changes before switching models.
Anti-Patterns
- Sending
budget_tokensto a model that rejects it - Assuming a default
displayand then showing users empty reasoning - Stripping or editing thinking blocks before returning tool results
- Raising effort globally without measuring quality and cost on real traffic
- A
max_tokenssized for a short answer with thinking on - Changing effort every turn and wondering why the cache stopped hitting
Best Practices
- Look up the per-model thinking table before writing the request
- Set
effortanddisplayexplicitly instead of relying on defaults - Pass assistant content back unmodified in tool loops
- Monitor
thinking_tokens, latency, andstop_reasonper route - Keep thinking and effort stable within a conversation
- Lower effort before reaching for prompt-based steering
References
- Thinking: https://platform.claude.com/docs/en/build-with-claude/thinking
- Steering thinking and cost: https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost
- Effort: https://platform.claude.com/docs/en/build-with-claude/effort
- Extended thinking (legacy manual mode): https://platform.claude.com/docs/en/build-with-claude/extended-thinking
- Migration guide: https://platform.claude.com/docs/en/about-claude/models/migration-guide