Steering thinking

Claude's thinking is adaptive: the model evaluates each request and decides for itself whether to think and how much. You set an intent, optionally specify the effort, and the model allocates reasoning where it judges reasoning will help.

This makes thinking a strong fit for workloads that mix trivial and complex requests, and for long-horizon agentic workflows where the right amount of reasoning varies from step to step.

For how to turn thinking on, how to read thinking output, and thinking output on Claude Fable 5 and Claude Mythos 5, see the Thinking overview. This page covers how Claude decides when to think, how to steer that decision, and the caching, cost, and pricing mechanics that follow from it.



How Claude decides when to think

Thinking is optional for the model. On each request, Claude weighs the complexity of the input and decides whether deeper reasoning would improve the answer. A simple factual question may get a direct response with no thinking block at all; a multistep math problem or a tricky debugging task triggers deeper reasoning.

The decision happens per request. The same conversation can contain turns with and without thinking, and a turn where Claude chose not to think contains no thinking block. Don't build application logic that assumes every assistant turn starts with one.

The primary control over this decision is the effort parameter, which acts as soft guidance for how willing Claude should be to think and how deeply; see Effort levels on this page for what each level does.

If you want Claude to think less often, lower the effort level before reaching for prompt-based steering.

Thinking also interleaves with tool use automatically: Claude can think between tool calls, reflecting on each tool result before deciding what to do next (interleaved thinking). You don't need a beta header or any additional configuration for this.

For the full picture of how the thinking configuration and the effort parameter interact, see Thinking and effort.



Steering how often Claude thinks

Whether Claude thinks on a given turn is promptable. Effort sets the overall posture, but you can also shape the decision directly with natural-language guidance, either globally in the system prompt or per message from the user turn.

Use the two levers together in this order:

1. Set the effort level that matches your workload's default balance of quality and latency.
2. Add prompt guidance only if Claude's triggering still doesn't match your needs at that level.

For broader prompting guidance with thinking, see leverage thinking and interleaved thinking capabilities.



Effort levels

Effort is the primary steering lever for thinking. Each level sets a different default for how often Claude thinks and how deeply:

This table describes how each level changes thinking behavior. For guidance on which level to choose for a given workload, including per-model recommendations, see When to adjust the effort parameter on the effort page.

Effort is set at output_config.effort, not inside the thinking object; for full per-language examples, see Effort.

{
  "model": "claude-opus-4-8",
  "max_tokens": 4096,
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

Level availability varies by model; the effort availability table on the effort page is the authority for which levels each model supports.



System prompt guidance

System prompt guidance shifts Claude's thinking threshold for every request in the conversation. If Claude is thinking more often than your workload needs, add guidance like this to your system prompt:

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multistep reasoning. When in doubt, respond directly.

To encourage thinking instead, use a phrase like:

This task involves multistep reasoning. Think carefully before responding.

Steering effectiveness can be sensitive to exact wording. If one phrasing doesn't produce the behavior you want, try a more direct variant.



Per-message steering

You can also steer thinking on a per-message basis from the user turn, independently of the system prompt. Appending "Please think hard before responding." to a user message encourages Claude to think on that turn; "Answer directly without deliberating." suppresses it.

Per-message steering is useful when only some requests in a conversation warrant extended reasoning. An agent harness, for example, can append the encouraging phrase on planning steps and the suppressing phrase on routine confirmations, without touching the system prompt or changing any request parameters between turns.



Verify steering on your workload

Prompt-based steering changes model behavior, so treat it like any other prompt change: measure before you ship. Run a representative sample of your traffic with and without the guidance, and compare how often thinking triggers (the presence of thinking blocks in responses), output token usage, latency, and answer quality on the cases that matter to you.



Mechanics

Three mechanics follow from Claude managing its own thinking: turn validation, prompt caching, and how you bound cost.



Turn validation

Assistant turns don't need to start with a thinking block. (Models using a legacy manual thinking budget enforce that the final assistant turn of a thinking-enabled request begins with one; see Turn structure in manual mode.)

For multi-turn applications, this means you can pass back conversation history in whatever shape you have it:

• Assistant turns where Claude chose not to think are valid history as-is.
• You can resume a conversation that began without thinking, or that used a different thinking configuration, without rewriting its history.
• History assembled from mixed sources doesn't need thinking blocks reinserted at the start of each assistant turn to pass validation.

The relaxation is about validation, not about what you should send. When you have thinking blocks, pass them back unmodified, particularly during tool use, where they carry the reasoning behind Claude's tool calls. See the Thinking overview for the full rules.



Prompt caching

Consecutive requests that keep the same thinking configuration and effort level preserve prompt caching; see Thinking and prompt caching for the full rules. The resolved effort value is rendered into the prompt, so changing it between requests invalidates cache breakpoints, just as changing the legacy budget_tokens parameter does on models that use it. Setting effort explicitly to the model's default is equivalent to omitting it and does not break the cache.

The practical consequence: pick a thinking configuration and an effort level per conversation and keep them. If some turns need more or less thinking, steer with per-message prompting: guidance appended to the newest user message leaves earlier cache breakpoints intact, where a configuration or effort change does not.

The following example demonstrates the invalidation with a multi-turn script you can run yourself:



Cost control

You don't set a thinking token budget. Two controls bound cost:

• max_tokens is a hard cap on total output for the request, thinking and response text combined. Claude never generates past it. In a tool-use loop, each request in the turn has its own max_tokens, so it doesn't bound the whole turn's spend.
• effort is soft guidance on how much of that output Claude allocates to thinking. It shapes behavior but doesn't guarantee a token count.

Because thinking counts toward max_tokens, set it high enough to leave room for both the reasoning and the answer. A max_tokens sized for a response with no thinking is often too small once Claude starts thinking on hard requests.

At high effort and above, Claude may think extensively and is more likely to exhaust the budget. If you see stop_reason: "max_tokens" in responses, you have two remedies:

• Raise max_tokens to give the model more room for thinking plus the answer.
• Lower the effort level so Claude thinks less and leaves more of the budget for response text.

Which one is right depends on whether the truncated responses needed the reasoning. If quality on those requests matters, raise the cap; if they were over-thought, lower the effort.



Pricing

Thinking incurs charges for:

• Tokens Claude uses while thinking (billed as output tokens)
• Thinking blocks from prior assistant turns that remain in context, per the preservation default: all turns by default on keep-all models, only the last turn elsewhere (billed as input tokens)
• Standard text output tokens

What you're billed for is the same regardless of the display setting; only what you see changes:

To see how many billed output tokens were spent on internal reasoning, read usage.output_tokens_details.thinking_tokens in the response. This value reflects the raw reasoning the model generated (not the summarized text returned in the body) and is always less than or equal to output_tokens. Subtract it from output_tokens to approximate the non-reasoning portion of the output. When streaming, this breakdown appears only on the final message_delta event.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens remains the inclusive, authoritative total used for billing. output_tokens_details is a read-only breakdown for observability. For complete pricing information including base rates, cache writes, cache hits, and output tokens, see Pricing.



Next steps