# Thinking And Effort

> Configure Claude's thinking and the effort parameter correctly — adaptive vs legacy budget-based thinking, the display setting, effort levels, thinking with tool use, cost control with max_tokens, and how thinking settings interact with prompt caching. Model behavior differs, so the skill shows how to check per-model rules instead of assuming them. Use this skill when enabling or tuning reasoning, migrating code that uses budget_tokens, debugging 400 errors on thinking parameters, empty thinking blocks, or truncated answers, or trading quality against latency and cost. Activate when: extended thinking, adaptive thinking, budget_tokens, effort parameter, output_config effort, thinking blocks, thinking display, interleaved thinking, reasoning tokens, thinking_tokens.

- Skill: `latestaiagents/thinking-and-effort` (Agent Skill)
- Install (CLI): `npx get-skill add latestaiagents/thinking-and-effort`
- Raw SKILL.md: https://api.skillmd.com/api/skills/latestaiagents/thinking-and-effort/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: latestaiagents (https://skillmd.com/u/latestaiagents)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/latestaiagents/thinking-and-effort

---


# 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_tokens` thinking
- A request returns 400 on its `thinking` field, 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_tokens` is rejected (400); some reject `disabled` too
- 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

```ts
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`:

```ts
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.

```ts
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_tokens` is a hard cap on thinking plus text for that request. If you see `stop_reason: "max_tokens"`, raise `max_tokens` or lower effort
- Thinking tokens are billed as output tokens. Read `usage.output_tokens_details.thinking_tokens` to see how much of `output_tokens` was 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

1. Sending `budget_tokens` to a model that rejects it
2. Assuming a default `display` and then showing users empty reasoning
3. Stripping or editing thinking blocks before returning tool results
4. Raising effort globally without measuring quality and cost on real traffic
5. A `max_tokens` sized for a short answer with thinking on
6. Changing effort every turn and wondering why the cache stopped hitting

## Best Practices

1. Look up the per-model thinking table before writing the request
2. Set `effort` and `display` explicitly instead of relying on defaults
3. Pass assistant content back unmodified in tool loops
4. Monitor `thinking_tokens`, latency, and `stop_reason` per route
5. Keep thinking and effort stable within a conversation
6. 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

