Extended Thinking, Effort & Multimodal Best Practices

Numbered practices for getting reliable, cost-efficient results out of extended thinking, the effort parameter, and multimodal input.

How to Use This List

• Treat each rule as a default to deviate from deliberately, not a rigid law.
• Apply the effort and thinking rules first, they affect cost on every request.
• Apply the multimodal rules when your workload includes images or documents.
• Revisit these periodically as usage patterns and cost targets shift.

A - Extended Thinking

• Enable adaptive thinking with thinking={"type": "adaptive"} rather than guessing a fixed reasoning budget. Adaptive thinking lets Claude calibrate depth per request, avoiding both under-reasoning on hard tasks and wasted reasoning on easy ones.
• Treat a missing thinking block as expected, not an error. Simple prompts often produce no visible reasoning under adaptive thinking; only investigate if a genuinely complex prompt returns none.
• Parse response.content by iterating and checking block.type, never by fixed index. The thinking block, when present, can occupy index 0, shifting the position of the text block.
• Budget max_tokens generously for prompts likely to trigger deep reasoning. Reasoning tokens and answer tokens share the same output budget, and a truncated thinking block can cut off the final answer.
• Log or store the thinking block separately from the user-facing answer. This supports debugging and auditing reasoning without conflating it with the response your users see.

B - Effort Tuning

• Map effort level to task type instead of hardcoding one setting for the whole application. Classification and extraction fit low, general assistant replies fit medium, code review and planning fit high, safety-critical analysis fits max.
• Benchmark latency and cost at each candidate effort level against real traffic before shipping a change. high and max can meaningfully slow down a user-facing endpoint; measure before committing.
• Build an evaluation set that includes your hardest real-world prompts before picking a default effort level. Effort's quality impact is most visible on genuinely hard tasks; testing only on easy prompts hides the difference.
• Validate effort strings against the known set (low, medium, high, max) before sending the request. Catching a typo like "med" at the call site is cheaper than debugging an opaque API error later.
• Reserve max effort for genuinely high-stakes calls. Applying it broadly "to be safe" inflates cost and latency across the whole application without a matching quality benefit on routine tasks.

C - Thinking Display

• Keep thinking display separate from effort in your mental model and your code. Effort controls reasoning depth and cost; display controls whether that reasoning is returned summarized or omitted.
• Default to omitted display for production, user-facing responses. Raw or even summarized reasoning is usually meant for debugging, not as the primary answer surface.
• Gate any reasoning display behind an explicit opt-in UI affordance. If you do show users a rationale, make it a deliberate "show reasoning" action rather than always-visible output.
• Retain summarized reasoning in an audit log for safety-critical or compliance-sensitive workloads, even when omitted from the end-user response. This preserves traceability without exposing internal reasoning to end users.
• Strip or summarize prior thinking blocks before appending them to a multi-turn conversation's history. Re-sending raw reasoning blocks as plain assistant text bloats token usage across a long conversation.

D - Sending Images

• Derive media_type from the actual file format, never hardcode or guess it. A mismatched media_type can cause a request error or a misread image.
• Always base64-encode image bytes with base64.standard_b64encode(...).decode("utf-8") before assigning to data. The API expects a base64 string, not raw bytes or a file path.
• Downscale or compress oversized images before encoding. Base64 inflates payload size by roughly a third over the raw file, and unnecessarily large images increase request size and cost.
• Pair every image block with a specific text instruction describing what to analyze. An image with no accompanying question leaves Claude guessing at intent.
• Prefer the Files API over inline base64 for any image or document used across more than one request. Re-sending the same encoded payload repeatedly wastes bandwidth and tokens for content that hasn't changed.

E - Files API and Multi-Request Documents

• Upload a document once and store its file_id durably, not just in a local variable. Persisting file_id alongside your own document identifier avoids redundant uploads across process runs.
• Handle the case where a referenced file_id has expired or is invalid. Retention policies vary by account; catch the error and re-upload if the source file is still available.
• Include only the relevant prior turns in a follow-up request's messages, not your entire local session history. The API only knows what's in the current request's messages list; keep fuller history locally for logging without resending all of it.
• Vary effort per question when asking a sequence of things about the same document. A simple lookup and a cross-referencing question have different reasoning needs, even against the same file.
• Set purpose explicitly on every Files API upload call. Omitting or mis-setting it can make the uploaded file unusable in a document content block later.

FAQs

Which practice matters most for cost control?

Mapping effort level to task type (practice B.1) usually has the largest cost impact, since it's the most direct lever on reasoning depth per request across your whole application.

Should I always enable adaptive thinking?

For most workloads, yes, it lets Claude calibrate reasoning depth per request rather than you guessing a fixed setting. The exception is extremely simple, high-volume tasks where the overhead of even checking for a thinking block isn't worth it.

Is it ever fine to show raw thinking output to users?

Occasionally, for specialized tooling audiences like developers reviewing code review output, but it should always be an explicit opt-in, not the default response surface.

What's the single most common multimodal mistake?

Mismatching media_type with the actual file format, or sending raw un-encoded bytes instead of a base64 string, both covered under practice D.

When should I switch from inline base64 to the Files API?

As soon as you expect to reference the same image or document in more than one request. One-off analysis is fine inline; anything reused benefits from the Files API's upload-once model.

How do I decide between low and max effort for a new endpoint?

Start by classifying the task's stakes and complexity, then benchmark latency and cost at a couple of candidate levels against real traffic before locking in a default.

Do these practices apply the same way across all four models in the lineup?

The mechanics apply the same way, but baseline reasoning capability differs by model (Fable 5, Opus 4.8, Sonnet 5, Haiku 4.5), so the same effort level won't produce identical depth or cost across models.

Why bother validating effort strings client-side?

An invalid value like "med" instead of "medium" otherwise surfaces as an opaque API error deep in a request path, rather than a clear validation failure at the call site.

Is thinking display purely a cost decision?

No, it's primarily a UX and data-sensitivity decision. Effort is the cost lever; display governs what reasoning content, if any, reaches the client or gets logged.

What's the risk of not persisting a file_id durably?

You lose the reference once the process holding it in memory ends, forcing a redundant re-upload the next time the document is needed, defeating the efficiency the Files API provides.

Should conversation history always be resent in full for document Q&A?

No, only include the prior turns relevant to the current question. Keep a fuller local history for your own tracking without resending the entire session on every call.

Is max effort ever wasteful even for a hard task?

Yes, if high effort already produces adequate quality for that task category, max adds cost and latency without a proportional benefit. Reserve it for the genuinely highest-stakes cases identified through evaluation.

Related

• Extended Thinking and the Effort Parameter Explained - the conceptual foundation for practices A through C.
• Tuning the effort Parameter for Cost and Speed - a deeper walkthrough of practice B.
• Effort Levels and Thinking Display Options Reference - the reference table these practices assume.
• Sending Images for Vision Analysis with Base64 Encoding - the full detail behind practice group D.
• Uploading and Referencing PDFs with the Files API - the full detail behind practice group E.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.