Reasoning Effort and Mode

Definition (confidence: high)

An API-level control surface for reasoning models: reasoning.effort tells the model how much to think, while reasoning.mode (GPT-5.6 family) selects the execution tier. Both are parameters passed in the request — distinct from prompt techniques like chain-of-thought, which coax reasoning out of the model through instructions. Effort and mode are independent: mode selects standard vs pro execution; effort controls how much reasoning happens within that mode. Omitting effort defaults to medium in both modes.

Effort Scale (confidence: high)

Value	Best for
none	Latency-critical tasks with no reasoning benefit (voice, fast retrieval, classification)
low	Tool-use, planning, search, multi-step decisions; data analysis, drafting, execution-oriented coding, chat
medium	Default for most workloads: planning, complex reasoning, judgement; balanced point on the latency/performance/cost pareto curve; agentic coding, research, spreadsheets/slides, long-horizon work
high	Hard reasoning, complex debugging, deep planning, high-value agentic tasks; long-horizon research
xhigh	Deep research, async workflows, long runs; only when evals justify the latency/cost
max	Maximum reasoning for the most complex tasks; evaluate max vs xhigh on real evals

Supported values and defaults are model-dependent (e.g. gpt-5.5 defaults to medium); some models support only a subset, so check the model page. Models also reason adaptively — fewer tokens for simpler tasks, more for complex ones.

Mode (confidence: high)

reasoning.mode: standard (default) or pro. Pro mode aggregates the model work performed into the final answer and bills those tokens at the selected model’s standard token rates — more work, not a premium rate; existing Pro model IDs keep their current behavior and pricing. Mode ≠ effort: raising mode is not a substitute for raising effort, and vice versa.

Reasoning Tokens and Budgeting (confidence: high)

• Reasoning tokens occupy context window space and bill as output tokens; visible via usage.output_tokens_details.reasoning_tokens.
• max_output_tokens caps reasoning + visible + formatting tokens. Exhaustion returns incomplete with reason: max_output_tokens — potentially before any visible output.
• OpenAI recommends reserving ~25,000 tokens for reasoning/outputs when starting out.
• gpt-5.5/gpt-5.4 support interleaved thinking: visible output tokens before and between thinking, and thinking between tool calls.

Prompting Advice (confidence: high)

Reasoning-capable GPT-5 models work best with a clear goal, strong constraints, and an explicit output contract without prescribing every intermediate step:

• Give the model the task, constraints, and desired output format.
• Treat reasoning.effort as a tuning knob, not the primary way to recover quality — a poorly specified prompt is not fixed by raising effort.
• For agentic or research-heavy workflows, define what counts as done and how the model should verify its work.
• For faster time to first visible token in latency-sensitive apps, ask for a short preamble before deeper reasoning.

Implications

Effort/mode move reasoning control from what you write to how you configure the request. The same prompt can produce very different cost/latency/quality trade-offs by adjusting one parameter. This reframes guidance: treat effort as a tuning knob, not a quality-recovery mechanism — a poorly specified prompt is not fixed by raising effort. It also creates a real failure mode the vault hadn’t catalogued before: truncation during reasoning, where you pay for thinking without receiving an answer. This is the inference-level complement to the user-facing reasoning patterns in paired-thinking-response.

Related Concepts (confidence: high)

chain-of-thought — prompt-level step-by-step reasoning technique, distinct from API-level effort control.

paired-thinking-response — user-facing hidden-reasoning patterns; OpenAI’s effort/mode design hides reasoning from the developer as well, exposing only token counts and summaries.

gpt-5-6 — the model family this parameter taxonomy primarily applies to.

Open Questions

• The minimal effort value sits between none and low in the API but its best-for row is not documented in the captured guide; check the live model page.
• Whether raising effort to max materially beats xhigh on real evals.

Sources

• raw/prompts/articles/openai-reasoning-models-guide.md
• raw/external/developers-openai-com-reasoning-bc1c15f2.md