API usage primer for Claude changedclaude_api_primer
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+11added
Lines−11removed
From line
67
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits22to this page, all time
### Prefilling Claude’s response ## Controlling Claude’s output ### Prefilling Claude's response ## Controlling Claude's output
The whole hunk
from line 67, old and new numbered
/
from line 67
6767
6868### Multiple conversational turns
6969
70The Messages API is stateless, which means that you always send the full conversational history to the API. You can use this pattern to build up a conversation over time. Earlier conversational turns don't necessarily need to actually originate from Claude. You can use synthetic `assistant` messages.
70The Messages API is stateless, which means that you always send the full conversational history to the API. You can use this pattern to build up a conversation over time. Earlier conversational turns don’t necessarily need to actually originate from Claude. You can use synthetic `assistant` messages.
7171
7272<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
7373 ```bash CLI
from line 100
100100 ```
101101</CodeGroup>
102102
103### Prefilling Claude's response
103### Prefilling Claude’s response
104104
105You can prefill part of Claude's response in the last position of the input messages list. Use this technique to shape Claude's response. The following example uses `"max_tokens": 1` to get a single multiple choice answer from Claude.
105You can prefill part of Claude’s response in the last position of the input messages list. Use this technique to shape Claude’s response. The following example uses `"max_tokens": 1` to get a single multiple choice answer from Claude.
106106
107107<Note>
108108 Claude 4.6 and later models and Claude Mythos Preview do not support assistant message prefill; requests to those models must end with a user message. The following examples use a model that supports prefill.
from line 316
316316
317317Important limitations:
318318
3191. **Tool choice limitation:** With manual extended thinking (`thinking: {"type": "enabled"}`), only `tool_choice: {"type": "auto"}` (default) or `tool_choice: {"type": "none"}` is supported. Adaptive thinking accepts forced tool use, except on the models listed under [Forcing tool use](https://platform.claude.com/docs/en/claude_api_primer#forcing-tool-use). Where it's accepted, a forced tool call skips thinking: the response starts with the tool call and has no `thinking` block.
3191. **Tool choice limitation:** With manual extended thinking (`thinking: {"type": "enabled"}`), only `tool_choice: {"type": "auto"}` (default) or `tool_choice: {"type": "none"}` is supported. Adaptive thinking accepts forced tool use, except on the models listed under [Forcing tool use](https://platform.claude.com/docs/en/claude_api_primer#forcing-tool-use). Where it’s accepted, a forced tool call skips thinking: the response starts with the tool call and has no `thinking` block.
3203202. **Preserving thinking blocks:** During tool use, you must pass `thinking` blocks back to the API for the last assistant message.
321321
322322### Preserving thinking blocks
from line 528
528528**Provide extremely detailed descriptions.** This is by far the most important factor in tool performance. Your descriptions should explain every detail about the tool, including:
529529
530530* What the tool does
531* When it should be used (and when it shouldn't)
532* What each parameter means and how it affects the tool's behavior
531* When it should be used (and when it shouldn’t)
532* What each parameter means and how it affects the tool’s behavior
533533* Any important caveats or limitations
534534
535535**Consider using `input_examples` for complex tools.** For tools with nested objects, optional parameters, or format-sensitive inputs, you can provide concrete examples using the `input_examples` field (beta). This shows Claude the expected input patterns. See [Providing tool use examples](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) for details.
from line 553
553553}
554554```
555555
556## Controlling Claude's output
556## Controlling Claude’s output
557557
558558### Forcing tool use
559559
from line 570
570570* `tool` forces Claude to always use a particular tool.
571571* `none` prevents Claude from using any tools.
572572
573On Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1, `any` and `tool` return a 400 error. Leave `tool_choice` at `auto` and set `"strict": true` on the tool definition to guarantee that any call Claude makes matches the tool's `input_schema`. See [Strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use).
573On Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1, `any` and `tool` return a 400 error. Leave `tool_choice` at `auto` and set `"strict": true` on the tool definition to guarantee that any call Claude makes matches the tool’s `input_schema`. See [Strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use).
574574
575575### JSON output
576576
from line 625
625625
626626### Handling the `max_tokens` stop reason
627627
628If Claude's response is cut off because it hits the `max_tokens` limit during tool use, retry the request with a higher `max_tokens` value.
628If Claude’s response is cut off because it hits the `max_tokens` limit during tool use, retry the request with a higher `max_tokens` value.
629629
630630### Handling the `pause_turn` stop reason
631631
from line 653
653653
654654### Invalid tool name
655655
656If Claude's attempted use of a tool is invalid (for example, missing required parameters), try the request again with more-detailed `description` values in your tool definitions.
656If Claude’s attempted use of a tool is invalid (for example, missing required parameters), try the request again with more-detailed `description` values in your tool definitions.
657657
658658## Streaming messages
659659
No line in this hunk matches that.