api-20261023T100709Z / page 4 of 6 / documentation capture

agents-and-tools/tool-use/bash-tool Changed · +1 / -1 lines

from line 181

181181

182182Claude responds with `stop_reason: "tool_use"` and a `tool_use` block that contains the command for your application to run:

183183

184```text Output wrap

184```json Output

185185{

186186 "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",

187187 "model": "claude-opus-5-5",

agents-and-tools/tool-use/define-tools Changed · +1 / -1 lines

from line 869

869869

870870For example, given the prompt "What's the weather like in San Francisco right now, and what time is it there?", Claude might respond with:

871871

872```text JSON

872```json JSON

873873{

874874 "role": "assistant",

875875 "content": [

agents-and-tools/tool-use/handle-tool-calls Changed · +1 / -1 lines

from line 23

2323A `tool_use` block for a member of the [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) or [browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) toolset also carries a `toolset_name` field (`"computer"` or `"browser"`). Its `name` is the member tool Claude is calling, such as `screenshot` or `navigate`, so dispatch those blocks on both fields.

2424

2525<Accordion title="Example API response with a `tool_use` content block">

26 ```text JSON wrap

26 ```json JSON

2727 {

2828 "id": "msg_01Aq9w938a90dw8q",

2929 "model": "claude-opus-5-5",

agents-and-tools/tool-use/memory-tool Changed · +2 / -2 lines

from line 48

4848

4949Claude calls the memory tool:

5050

51```text wrap

51```json

5252{

5353 "type": "tool_use",

5454 "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",

from line 72

7272

7373**4. Claude reads relevant files:**

7474

75```text wrap

75```json

7676{

7777 "type": "tool_use",

7878 "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",

agents-and-tools/tool-use/overview Changed · +1 / -1 lines

from line 654

654654

655655 For example, given a `get_weather` tool that requires a `location` parameter, if you ask Claude "What's the weather?" without specifying a location, Claude (particularly Claude Sonnet) might guess values you didn't supply:

656656

657 ```text JSON wrap

657 ```json JSON

658658 {

659659 "type": "tool_use",

660660 "id": "toolu_01A09q90qw90lq917835lq9",

agents-and-tools/tool-use/strict-tool-use Changed · +1 / -1 lines

from line 349

349349

350350**Response format:** Tool use blocks with validated inputs in `response.content[x].input`

351351

352```text Output wrap

352```json Output

353353{

354354 "type": "tool_use",

355355 "name": "get_weather",

api/beta-headers Changed · +1 / -1 lines

from line 209

209209

210210If you use an invalid beta name, or a beta your organization doesn't have access to, you'll receive a `400` error response:

211211

212```text Output

212```json Output

213213{

214214 "type": "error",

215215 "error": {

api/claude-code/routines-fire Changed · +2 / -2 lines

from line 95

9595

9696A successful request returns `200 OK` with the new session details:

9797

98```text

98```json

9999{

100100 "type": "routine_fire",

101101 "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",

from line 113

113113

114114Errors use the standard Anthropic [error envelope](https://platform.claude.com/docs/en/api/errors):

115115

116```text wrap

116```json

117117{

118118 "type": "error",

119119 "error": {

api/rate-limits Changed · +1 / -1 lines

from line 46

4646

4747Once you reach your tier's spend cap, API usage pauses until 00:00 UTC on the first day of the next month, unless you request a higher limit sooner. While usage is paused, API requests return HTTP 429:

4848

49```text

49```json

5050{

5151 "type": "error",

5252 "error": {

api/service-tiers Changed · +1 / -1 lines

from line 187

187187

188188The response `usage` object also includes the service tier assigned to the request:

189189

190```text wrap

190```json

191191{

192192 "usage": {

193193 "input_tokens": 410,

build-with-claude/cache-diagnostics Changed · +1 / -1 lines

from line 973

973973

974974When `cache_miss_reason` is non-null, it looks like this:

975975

976```text wrap

976```json

977977{

978978 "id": "msg_01Xyz...",

979979 "type": "message",

build-with-claude/compaction-on-demand Changed · +1 / -1 lines

from line 280

280280 ```

281281</CodeGroup>

282282

283```text Response

283```json Response

284284{

285285 "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",

286286 "type": "message",

build-with-claude/compaction-threshold Changed · +2 / -2 lines

from line 1365

13651365

13661366A long-running conversation might result in multiple compactions. The last compaction block reflects the final state of the prompt, replacing content prior to it with the generated summary.

13671367

1368```text Output

1368```json Output

13691369{

13701370 "content": [

13711371 {

from line 2256

22562256

22572257Compaction requires an additional sampling step, which contributes to rate limits and billing. The API returns detailed usage information in the response:

22582258

2259```text Output wrap

2259```json Output

22602260{

22612261 "usage": {

22622262 "input_tokens": 23000,

build-with-claude/effort Changed · +1 / -1 lines

from line 268

268268

269269### Recommended effort levels for Claude Opus 5

270270

271Claude Opus 5 supports all five effort levels. **Start with `high`, the default**, and adjust based on your evals: step up to `xhigh` for demanding coding and agentic work, or to `max` when a task justifies unconstrained token spending, and use `low` and `medium` liberally as your primary control for token cost and response time wherever your evals show quality holds. If you carried effort settings over from an earlier model, run a fresh effort sweep on your evals rather than reusing them.

271Claude Opus 5 supports all five effort levels. **Start with `high`, the default**, and adjust based on your evals: step up to `xhigh` for demanding coding and agentic work, or to `max` when a task justifies unconstrained token spending. Use `low` and `medium` liberally as your primary control for token cost and response time wherever your evals show quality holds. If you carried effort settings over from an earlier model, run a fresh effort sweep on your evals rather than reusing them.

272272

273273Effort controls thinking volume, not visible response length: on Claude Opus 5, changing effort does not reliably shorten responses, so [prompt for length](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#response-length-and-verbosity) instead.

274274

build-with-claude/embeddings Changed · +1 / -1 lines

from line 142

142142

143143The response is a JSON object containing the embeddings and the token usage:

144144

145```text wrap

145```json

146146{

147147 "object": "list",

148148 "data": [

build-with-claude/fast-mode Changed · +1 / -1 lines

from line 375

375375 ```

376376</CodeGroup>

377377

378```text Output wrap

378```json Output

379379{

380380 "id": "msg_01XFDUDYJgAACzvnptvVoYEL",

381381 "type": "message",

build-with-claude/files Changed · +2 / -2 lines

from line 143

143143

144144The response from uploading a file includes:

145145

146```text Response wrap

146```json Response

147147{

148148 "id": "file_011CNha8iCJcU1wXNR6q4V8w",

149149 "type": "file",

from line 997

997997* **File too large (413):** The file exceeds the 500 MB limit.

998998* **Storage limit exceeded (400):** Your organization has reached the 1 TB storage limit.

999999

1000```text Output wrap

1000```json Output

10011001{

10021002 "type": "error",

10031003 "error": {

build-with-claude/handling-stop-reasons Changed · +2 / -2 lines

from line 24

2424

2525The `stop_reason` field is part of every successful Messages API response. Unlike errors, which indicate failures in processing your request, `stop_reason` tells you why Claude completed its response generation.

2626

27```text Example response wrap

27```json Example response

2828{

2929 "id": "msg_01234",

3030 "type": "message",

from line 1484

14841484 With [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling), the same response shape means something different. The client `tool_use` block comes from code that is running in the `code_execution` tool rather than from Claude directly, and its `caller` field names the `code_execution` block that called it. That code has already started: it is paused waiting for your `tool_result` blocks, and sending them resumes the execution instead of starting a deferred tool. The `code_execution` block's own result block arrives once the code completes, which can take more than one round of tool results. The follow-up user message itself is the same in both cases; with programmatic tool calling, also pass back the `id` from the response's `container` field, as that page shows.

14851485</Note>

14861486

1487```text A mixed tool_use response wrap

1487```json A mixed tool_use response

14881488{

14891489 "stop_reason": "tool_use",

14901490 "content": [

build-with-claude/mid-conversation-system-messages Changed · +1 / -1 lines

from line 993

993993

994994The response's `content` includes a `tool_use` block for the new tool, for example:

995995

996```text

996```json

997997{

998998 "type": "tool_use",

999999 "id": "toolu_01A09q90qw90lq917835lq9",

build-with-claude/pdf-support Changed · +2 / -2 lines

from line 85

8585</Note>

8686

8787<Note>

88 Plain text files such as .txt, .csv, or .md can be used directly in document blocks: upload them to the Files API with MIME type `text/plain` and reference them by `file_id`. Binary formats such as .xlsx or .docx are not supported in document blocks and must be converted to text or PDF first. See [Working with other file formats](https://platform.claude.com/docs/en/build-with-claude/files#working-with-other-file-formats).

88 Plain text files such as .txt, .csv, or .md can be used directly in document blocks: upload them to the Files API with MIME type `text/plain` and reference them by `file_id`. Binary formats such as .xlsx or .docx are not supported in document blocks, so convert them to text or PDF first. See [Working with other file formats](https://platform.claude.com/docs/en/build-with-claude/files#working-with-other-file-formats).

8989</Note>

9090

9191## Process PDFs with Claude

from line 349

349349

350350The response returns Claude's analysis as text blocks in `content`, with token consumption in `usage`:

351351

352```text Output

352```json Output

353353{

354354 "id": "msg_01Hfp8YuFjQ55VgWbpdHDehB",

355355 "type": "message",

build-with-claude/prompt-caching Changed · +2 / -2 lines

from line 821

821821

822822The response includes detailed cache information like the following:

823823

824```text Output wrap

824```json Output

825825{

826826 "usage": {

827827 "input_tokens": 2048,

from line 1090

10901090

10911091The API returns an empty `content` array:

10921092

1093```text Output wrap

1093```json Output

10941094{

10951095 "id": "msg_01XFDUDYJgAACzvnptvVoYEL",

10961096 "type": "message",

build-with-claude/skills-guide Changed · +1 / -1 lines

from line 1949

19491949## Managing custom Skills

19501950

19511951<Warning id="workspace-scoped-access">

1952 **Custom Skills are accessible to your entire workspace, not scoped to an end user, conversation, or session.** Any API key with access to a workspace can read, use, and delete every custom Skill uploaded to that workspace. Every service account, and every user whose organization role allows API access, can use the Default Workspace in addition to any workspace you add them to, so keep Skills that must stay separate in their own workspace and access them only with [keys scoped to that workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#api-keys-and-resource-scoping).

1952 **Custom Skills are accessible to your entire workspace, not scoped to an end user, conversation, or session.** Any API key with access to a workspace can read, use, and delete every custom Skill uploaded to that workspace. Every service account, and every user whose organization role allows API access, can use the Default Workspace in addition to any workspace you add them to. For that reason, keep Skills that must stay separate in their own workspace and access them only with [keys scoped to that workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#api-keys-and-resource-scoping).

19531953

19541954 If you are building a multitenant platform on the Skills API, create a separate [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces) for each tenant. The workspace is the isolation boundary for custom Skills, so a workspace for each tenant gives that tenant's Skills hard isolation from every other tenant. Each organization can have up to 100 workspaces by default (see [How workspaces work](https://platform.claude.com/docs/en/manage-claude/workspaces#how-workspaces-work)); if you need more for tenant isolation, contact your account team.

19551955</Warning>

build-with-claude/task-budgets Changed · +1 / -1 lines

from line 312

312312

313313Claude thinks, then emits a tool call and stops with `stop_reason: "tool_use"`:

314314

315```text

315```json

316316{

317317 "role": "assistant",

318318 "content": [

build-with-claude/thinking-steering-and-cost Changed · +1 / -1 lines

from line 889

889889

890890To see how many billed output tokens were spent on internal reasoning, read `usage.output_tokens_details.thinking_tokens` in the response. This value reflects the raw reasoning the model generated (not the summarized text returned in the body) and is always less than or equal to `output_tokens`. Subtract it from `output_tokens` to approximate the non-reasoning portion of the output. When streaming, this breakdown appears only on the final `message_delta` event.

891891

892```text wrap

892```json

893893{

894894 "usage": {

895895 "input_tokens": 25,

build-with-claude/thinking-tool-workflows Changed · +2 / -2 lines

from line 287

287287 To see thinking text like this output, add `display: "summarized"` to the request. On models where display defaults to omitted, including Claude Opus 5.5, the `thinking` field otherwise comes back as an empty string with only the `signature` populated. Either way, echo the content array back unchanged; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).

288288 </Note>

289289

290 ```text Output

290 ```json Output

291291 {

292292 "content": [

293293 {

from line 753

753753 <Step title="Read the final response">

754754 You should see Claude complete the turn with text. Because [interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#interleaved-thinking) is automatic in adaptive mode, the continuation can also open with a new thinking block before the final text:

755755

756 ```text Output wrap

756 ```json Output

757757 {

758758 "content": [

759759 {

One read of Claude Developer Platformapi-20261023T100709Z

What this read moved