Claude Platform Docs
MessagesEffort

Effort

Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency.

Usage differs by product

Messages API
Set output_config.effort on the request. With no value, the model’s default level applies.
Managed Agents
Set effort on the agent’s model object, or in a session’s model override. With no value, Managed Agents fills in the model’s default.

The effort parameter lets you control how many tokens Claude spends when responding to requests. You can trade off between response thoroughness and token efficiency with a single model.

Set the effort level

Set output_config.effort on the request. The following example runs one request at medium effort.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

How effort works

Most Claude models default to high effort, spending as many tokens as needed for excellent results; Claude Opus 5.5 and Claude Haiku 5.5 default to medium. You can raise the effort level to max for the absolute highest capability, or lower it to be more conservative with token usage, optimizing for speed and cost while accepting some reduction in capability.

The effort parameter affects all tokens in the response, including:

  • Text responses and explanations
  • Tool calls and function arguments
  • Thinking (when active)

Because effort applies to every output token, it works with or without thinking. Lower effort also means fewer and terser tool calls.

Effort levels

LevelDescriptionTypical use case
maxAbsolute maximum capability with no constraints on token spending. Available on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, and Claude Haiku 5.5.Tasks requiring the deepest possible reasoning and most thorough analysis
xhighExtended capability for long-horizon work. Available on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5, and Claude Haiku 5.5.Long-running agentic and coding tasks (over 30 minutes) with token budgets in the millions
highSpends as many tokens as the task needs for excellent results. The default on every model that supports effort except Claude Opus 5.5 and Claude Haiku 5.5.Complex reasoning, difficult coding problems, agentic tasks
mediumBalanced approach with moderate token savings. The default on Claude Opus 5.5 and Claude Haiku 5.5.Agentic tasks that require a balance of speed, cost, and performance
lowMost efficient. Significant token savings with some capability reduction.Simpler tasks that need the best speed and lowest costs, such as subagents

Not every model that supports max supports xhigh.

The per-model recommendations that follow override this table where they differ.

Differs by model

Claude Fable 5.2 & Claude Mythos 5.2For demanding reasoning and long-horizon agentic work

Claude Fable 5.2 supports all five effort levels. The API default is high. Adaptive thinking is always on, so effort is your main control for thinking depth, latency, and cost.

Start with high. Most of the gain in capability is already present at high, and above it, gains are uneven and depend on the task. Step up to xhigh for your hardest long-running coding and agentic work, where you’ve measured a gain. Step down to medium or low where your evals show quality holds. Reserve max for measuring the model’s ceiling and for the rare task where time and tokens don’t matter. At max the model optimizes for capability without regard to token cost. It runs slower and costs more than at xhigh, often for only a small gain.

Run an effort sweep on your own evals rather than carrying settings over from Claude Fable 5.1. At high and above, set a large max_tokens. It’s a hard limit on total output (thinking plus response text). Effort barely changes how long the model’s replies are, so use your prompt to change reply length and tone.

The same recommendations apply to Claude Mythos 5.2.

On supported platforms, Claude Fable 5.2 and Claude Mythos 5.2 also support changing effort mid-conversation with a per-message output_config, which preserves the prompt cache.

Effort with tool use

When using tools, the effort parameter affects both the explanations around tool calls and the tool calls themselves. Lower effort levels tend to:

  • Combine multiple operations into fewer tool calls
  • Make fewer tool calls
  • Proceed directly to action without preamble
  • Use terse confirmation messages after completion

Higher effort levels might:

  • Make more tool calls
  • Explain the plan before taking action
  • Provide detailed summaries of changes
  • Include more comprehensive code comments

Effort with thinking

The thinking parameter controls whether Claude thinks in thinking blocks before answering; the effort parameter controls how much work Claude puts into the whole response, which in adaptive mode includes how often and how deeply it thinks. Don’t pass adaptive as an effort value: adaptive is a thinking mode, not an effort level.

At higher effort levels, Claude thinks more readily and at greater length. In a tool-use loop, follow-up requests that only process tool results can still skip thinking at any level. At lower levels, Claude can skip thinking entirely for simpler problems. See Thinking and effort for full guidance on how the two controls work together.

On Claude Opus 4.5, the only extended-thinking-only model that supports effort, it works alongside budget_tokens: set the effort level for your task, then set the thinking token budget based on how much reasoning depth the task needs.

For per-model thinking availability, see the per-model configuration table. Effort works with or without thinking. See How effort works.

Change effort mid-conversation

You can run later turns of a conversation at a different effort level in two ways. A per-message effort change keeps the prompt cache. A new top-level value on the next request can invalidate all or part of the prompt cache.

Per-message effort

Per-message effort sets a new level with a system message in messages.

Top-level effort on the next request

The top-level output_config.effort applies to the whole request. To run a later part of a conversation at a different level, set the new value on the next request. Because top-level effort shapes the rendered prompt, changing it between requests can invalidate cached prefixes from earlier turns. If you rely on prompt caching across a long session and your model doesn’t support per-message effort, pick an effort level at the start and keep it constant.

Best practices

  1. Set effort explicitly: The API defaults to high (medium on Claude Opus 5.5 and Claude Haiku 5.5), but the right starting point depends on your model and workload.
  2. Use low for speed-sensitive or simple tasks: When latency matters or tasks are straightforward, low effort can significantly reduce response times and costs.
  3. Test your use case: The impact of effort levels varies by task type. Evaluate performance on your specific use cases before deploying.
  4. Consider dynamic effort: Adjust effort based on task complexity. Simple queries might warrant low effort, whereas agentic coding and complex reasoning benefit from high effort. See the next item before varying it within one conversation.
  5. Hold top-level effort constant within cached conversations: Changing the top-level effort value between requests can invalidate all or part of the prompt cache, so vary it across workloads rather than within a conversation that relies on cache hits. On models that support it, use a per-message effort change instead, which preserves the cache. See Thinking and prompt caching.

Next steps

Give Claude an advisory token budget for the full agentic loop to help the model self-regulate on long agentic tasks.

Understand adaptive thinking, where Claude determines when and how much to think, and steer it with effort and prompting.

Understand how thinking works, when Claude thinks by default, and how thinking interacts with effort.

Availability

Effort
APIs
  • Messages API
  • Managed Agents
Models
  • Claude Fable 5.2, Fable 5.1, Fable 5
  • Claude Mythos 5.2, Mythos 5.1, Mythos 5, Mythos Preview
  • Claude Opus 5.5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5
  • Claude Sonnet 5.5, Sonnet 5, Sonnet 4.6
  • Claude Haiku 5.5

Applicable endpoints

  • /v1/messages with effort
Zero data retentionEligible

Excludes Covered Models

HIPAAEligible

Was this page helpful?