Home Docs Claude Developer Platform 21 Oct 2026

One change · api

Process results programmatically changedagents-and-tools/tool-use/programmatic-tool-calling

Nearest release: v2.1.307, published an hour after 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 21 Oct 2026 19:37 UTC

Lines+80added

Lines−80removed

From line 32 where the diff opens

First seen 14 Aug 2026 this site's first read of the page

Recorded edits14to this page, all time

The whole hunk

from line 32, old and new numbered

lines

from line 32

3232 - Claude Haiku 4.5 accepts the `code_execution_20260120` and later tool versions but doesn't support programmatic tool calling.

3333---

3434

35Programmatic tool calling allows Claude to write code that calls your tools programmatically within a [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) container, rather than requiring round trips through the model for each tool invocation. This reduces latency for multi-tool workflows and decreases token consumption by allowing Claude to filter or process data before it reaches the model's context window. On agentic search benchmarks like [BrowseComp](https://arxiv.org/abs/2504.12516) and [DeepSearchQA](https://github.com/google-deepmind/deepsearchqa), which test multistep web research and complex information retrieval, adding programmatic tool calling on top of basic search tools improved performance by an average of 11% while using 24% fewer input tokens (see [Improved web search with dynamic filtering](https://claude.com/blog/improved-web-search-with-dynamic-filtering)).

35Programmatic tool calling allows Claude to write code that calls your tools programmatically within a [code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) container, rather than requiring round trips through the model for each tool call. This reduces latency for multi-tool workflows and decreases token consumption by allowing Claude to filter or process data before it reaches the model's context window. On agentic search benchmarks such as [BrowseComp](https://arxiv.org/abs/2504.12516) and [DeepSearchQA](https://github.com/google-deepmind/deepsearchqa), which test multistep web research and complex information retrieval, adding programmatic tool calling on top of basic search tools improved performance by an average of 11 percent while using 24 percent fewer input tokens (see [Improved web search with dynamic filtering](https://claude.com/blog/improved-web-search-with-dynamic-filtering)).

3636

37Consider checking budget compliance across 20 employees: the traditional approach requires 20 separate model round-trips, pulling thousands of expense line items into the context along the way. With programmatic tool calling, a single script runs all 20 lookups, filters the results, and returns only the employees who exceeded their limits, shrinking what Claude needs to reason over from hundreds of kilobytes down to a handful of lines.

3838

3939<Tip>

4040 For a deeper look at the inference and context costs that programmatic tool calling addresses, see [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use).

from line 49

4949<CodeGroup>

5050 ```bash cURL

5151 curl https://api.anthropic.com/v1/messages \

52 --header "x-api-key: $ANTHROPIC_API_KEY" \

53 --header "anthropic-version: 2023-06-01" \

54 --header "content-type: application/json" \

55 --data '{

52 -H "x-api-key: $ANTHROPIC_API_KEY" \

53 -H "anthropic-version: 2023-06-01" \

54 -H "content-type: application/json" \

55 -d '{

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

5757 "max_tokens": 4096,

5858 "messages": [

from line 326

326326 client = Anthropic::Client.new

327327

328328 message = client.messages.create(

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

329 model: Anthropic::Model::CLAUDE_OPUS_5_5,

330330 max_tokens: 4096,

331331 messages: [

332332 {

from line 361

361361 ```

362362</CodeGroup>

363363

364The response stops with `stop_reason: "tool_use"`, a `container` ID, and a `tool_use` block for `query_database` whose `caller` field identifies the code execution run that called it. Return the result as shown in [Step 3 of the example workflow](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling#step-3-provide-tool-result) so the code can finish.

365365

366366## How programmatic tool calling works

367367

368368When you configure a tool to be callable from code execution and Claude determines that tool is needed:

369369

3701. Claude writes Python code that invokes the tool as a function, potentially including multiple tool calls and pre/post-processing logic

3712. Claude runs this code in a sandboxed container through code execution

3723. When a tool function is called, code execution pauses and the API returns a `tool_use` block

3734. You provide the tool result, and code execution continues (intermediate results are not loaded into Claude's context window)

3745. Once all code execution completes, Claude receives the final output and continues working on the task

3701. Claude writes Python code that invokes the tool as a function, potentially including multiple tool calls and pre/post-processing logic.

3712. Claude runs this code in a sandboxed container through code execution.

3723. When a tool function is called, code execution pauses and the API returns a `tool_use` block.

3734. You provide the tool result, and code execution continues (intermediate results are not loaded into Claude's context window).

3745. Once all code execution completes, Claude receives the final output and continues working on the task.

375375

376376This approach is particularly useful for:

377377

378* **Large data processing:** Filter or aggregate tool results before they reach Claude's context

379* **Multistep workflows:** Save tokens and latency by calling tools serially or in a loop without sampling Claude in-between tool calls

380* **Conditional logic:** Make decisions based on intermediate tool results

378* **Large data processing:** Filter or aggregate tool results before they reach Claude's context.

379* **Multistep workflows:** Save tokens and latency by calling tools serially or in a loop without sampling Claude in-between tool calls.

380* **Conditional logic:** Make decisions based on intermediate tool results.

381381

382382<Note>

383383 Tools that allow a code execution caller are exposed to Claude's code as async Python functions, so Claude can run them in parallel with `asyncio.gather`. Each function takes a single dict of arguments and returns a string: the text of the `tool_result` you send back. Claude's code awaits these functions with top-level `await` and parses results that it needs as structured data, for example `rows = json.loads(await query_database({"sql": "<sql>"}))`.

from line 387

387387

388388### The `allowed_callers` field

389389

390The `allowed_callers` field specifies which contexts can invoke a tool:

390The `allowed_callers` field specifies which contexts can call a tool:

391391

392392```json

393393{

from line 402

402402

403403**Possible values:**

404404

405* `["direct"]` - Claude is guided to call this tool directly (default if omitted)

406* `["code_execution_20260120"]` - Claude is guided to call this tool only from within code execution

407* `["direct", "code_execution_20260120"]` - Claude may call this tool directly or from within code execution

405* `["direct"]` - Claude is guided to call this tool directly (default if omitted).

406* `["code_execution_20260120"]` - Claude is guided to call this tool only from within code execution.

407* `["direct", "code_execution_20260120"]` - Claude may call this tool directly or from within code execution.

408408

409409Both `"code_execution_20260120"` and `"code_execution_20260521"` are accepted in `allowed_callers` and are interchangeable: a request using either code-execution tool version satisfies tools that list either caller. Response blocks always tag the caller as `code_execution_20260120` regardless of which version the request declared.

410410

from line 413

413413</Tip>

414414

415415<Note>

416 `allowed_callers` controls how the tool is presented to Claude and is validated against `tool_choice`, but it is not a hard API-level block on direct invocation. Claude is strongly guided to respect it, but your client should still be prepared to handle a direct `tool_use` for any tool it defines. Do not rely on `allowed_callers` as a security boundary.

416 `allowed_callers` controls how the tool is presented to Claude and is validated against `tool_choice`, but it is not a hard API-level block on direct calls. Claude is strongly guided to respect it, but your client should still be prepared to handle a direct `tool_use` for any tool it defines. Do not rely on `allowed_callers` as a security boundary.

417417</Note>

418418

419419### The `caller` field in responses

420420

421Every tool use block includes a `caller` field indicating how it was invoked:

421Every tool use block includes a `caller` field indicating how it was called:

422422

423**Direct invocation (traditional tool use):**

423**Direct call (traditional tool use):**

424424

425425```json

426426{

from line 432

432432}

433433```

434434

435**Programmatic invocation:**

435**Programmatic call:**

436436

437437```json

438438{

from line 453

453453

454454Programmatic tool calling uses the same containers as code execution:

455455

456* **Container creation:** A new container is created for each request unless you reuse an existing one

457* **Container ID:** Returned in responses in the `container` field, along with an `expires_at` timestamp

456* **Container creation:** A new container is created for each request unless you reuse an existing one.

457* **Container ID:** Returned in responses in the `container` field, along with an `expires_at` timestamp.

458458* **Reuse:** Pass the container ID back on the next request to keep state. While a programmatic tool call is waiting for your result, the container ID is required on that request, not optional: the API rejects the request without it.

459459* **Expiration:** `expires_at` tells you how long the container has left. Idle containers are currently reclaimed after about 5 minutes, and no container can be reused more than 30 days after it was created.

460460

from line 526

526526<CodeGroup>

527527 ```bash cURL

528528 curl https://api.anthropic.com/v1/messages \

529 --header "x-api-key: $ANTHROPIC_API_KEY" \

530 --header "anthropic-version: 2023-06-01" \

531 --header "content-type: application/json" \

532 --data '{

529 -H "x-api-key: $ANTHROPIC_API_KEY" \

530 -H "anthropic-version: 2023-06-01" \

531 -H "content-type: application/json" \

532 -d '{

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

534534 "max_tokens": 4096,

535535 "container": "container_xyz789",

from line 1203

12031203

12041204This pattern:

12051205

1206* Reduces model round-trips from N (one per region) to 1

1206* Reduces model round-trips from N (one for each region) to 1

12071207* Processes large result sets programmatically before returning to Claude

12081208* Saves tokens by only returning aggregated conclusions instead of raw data

12091209

from line 1301

13011301

13021302### Common errors

13031303

1305| ------------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |

1306| `invalid_tool_input` | `error_code` on the `code_execution_tool_result` error block in the response | Invalid parameters were passed to the code execution tool | See the [code execution tool errors](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#errors) |

1307| `invalid_request_error` (on `tool_choice`) | HTTP 400 error response | `tool_choice` names a tool whose `allowed_callers` does not include `"direct"` | Either add `"direct"` to that tool's `allowed_callers`, or remove the tool from `tool_choice` and let Claude invoke it from code |

13081308

13091309### Container expiration during tool call

13101310

1311If your tool result doesn't arrive within about 4 minutes, the pending call raises a `TimeoutError` inside Claude's running code. Claude sees the error in `stderr` and typically retries the call:

1311If your tool result doesn't arrive within about 4 minutes, the pending call raises a `TimeoutError` inside Claude's running code. Claude receives the error in `stderr` and typically retries the call:

13121312

13131313```json

13141314{

from line 1326

13261326

13271327To prevent timeouts:

13281328

1329* Monitor the `expires_at` field in responses

1330* Implement timeouts for your tool execution

1331* Consider breaking long operations into smaller chunks

1329* Monitor the `expires_at` field in responses.

1330* Implement timeouts for your tool execution.

1331* Consider breaking long operations into smaller chunks.

13321332

13331333### Tool execution errors

13341334

from line 1348

13481348

13491349### Feature incompatibilities

13501350

1351* **Structured outputs:** Tools with `strict: true` are not supported with programmatic calling

1352* **Tool choice:** You cannot force programmatic calling of a specific tool through `tool_choice`

1353* **Parallel tool use:** `disable_parallel_tool_use: true` is not supported with programmatic calling

1351* **Structured outputs:** Tools with `strict: true` are not supported with programmatic calling.

1352* **Tool choice:** You cannot force programmatic calling of a specific tool through `tool_choice`.

1353* **Parallel tool use:** `disable_parallel_tool_use: true` is not supported with programmatic calling.

13541354

13551355### Input schema limitations

13561356

from line 1374

13741374

13751375**Tool result only responses:** If there are pending programmatic tool calls waiting for results, your response message must contain **only** `tool_result` blocks. You cannot include any text content, even after the tool results.

13761376

1377Invalid - Cannot include text when responding to programmatic tool calls:

1377Invalid (cannot include text when responding to programmatic tool calls):

13781378

13791379```json

13801380{

from line 1390

13901390}

13911391```

13921392

1393Valid - Only tool results when responding to programmatic tool calls:

1393Valid (only tool results when responding to programmatic tool calls):

13941394

13951395```json

13961396{

from line 1411

14111411

14121412### Rate limits

14131413

1414Programmatic tool calls are subject to the same rate limits as regular tool calls. Each tool call from code execution counts as a separate invocation.

1414Programmatic tool calls are subject to the same rate limits as regular tool calls. Each tool call from code execution counts toward those limits individually.

14151415

14161416### Validate tool results before use

14171417

14181418When implementing user-defined tools that will be called programmatically:

14191419

1420* **Tool results are returned as strings:** They can contain any content, including code snippets or executable commands that may be processed by the execution environment.

1421* **Validate external tool results:** If your tool returns data from external sources or accepts user input, be aware of code injection risks if the output will be interpreted or executed as code.

1420* **Tool results are returned as strings:** They can contain any content, including code snippets or executable commands that might be processed by the execution environment.

1421* **Validate external tool results:** If your tool returns data from external sources or accepts user input, be aware of code injection risks if the output is interpreted or run as code.

14221422

14231423## Token efficiency

14241424

from line 1425

14251425Programmatic tool calling reduces token consumption in three ways:

14261426

14271427* **Tool results from programmatic calls are not added to Claude's context** - only the final code output is

1428* **Intermediate processing happens in code** - filtering, aggregation, and other transformations don't consume model tokens

1428* **Intermediate processing occurs in code** - filtering, aggregation, and other transformations don't consume model tokens

14291429* **Multiple tool calls in one code execution** - reduces overhead compared to separate model turns

14301430

14311431For example, calling 10 tools directly uses \~10x the tokens of calling them programmatically and returning a summary.

from line 1432

14321432

14331433In Anthropic's internal evaluations on a production Claude model:

14341434

1435* On a 75-tool project-management agent benchmark, enabling programmatic tool calling reduced billed input tokens by roughly 38% with no change in task accuracy.

1436* On [τ²-bench](https://arxiv.org/abs/2506.07982) (airline, retail, and telecom domains), where each turn makes one or two sequential tool calls, programmatic tool calling left scores unchanged and cost roughly 8% more. Sequential single-call workflows do not benefit.

1437* Across production API traffic, requests whose `tools` array contains 10 to 49 tool definitions see typical token savings of 20% to 40% with programmatic tool calling enabled.

1435* On a 75-tool project-management agent benchmark, enabling programmatic tool calling reduced billed input tokens by roughly 38 percent with no change in task accuracy.

1436* On [τ²-bench](https://arxiv.org/abs/2506.07982) (airline, retail, and telecom domains), where each turn makes one or two sequential tool calls, programmatic tool calling left scores unchanged and cost roughly 8 percent more. Sequential single-call workflows do not benefit.

1437* Across production API traffic, requests whose `tools` array contains 10 to 49 tool definitions see typical token savings of 20 to 40 percent with programmatic tool calling enabled.

14381438

14391439Actual savings vary with workload shape. See [When to use programmatic calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling#when-to-use-programmatic-calling).

14401440

from line 1443

14431443Programmatic tool calling uses the same pricing as code execution. See the [code execution pricing](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#usage-and-pricing) for details.

14441444

14451445<Note>

1446 Token counting for programmatic tool calls: Tool results from programmatic invocations do not count toward your input/output token usage. Only the final code execution result and Claude's response count.

1446 Token counting for programmatic tool calls: Tool results from programmatic calls do not count toward your input/output token usage. Only the final code execution result and Claude's response count.

14471447</Note>

14481448

14491449## Best practices

from line 1450

14501450

14511451### Tool design

14521452

1453* **Provide detailed output descriptions:** Because Claude deserializes tool results in code, document the format (JSON structure and field types)

1454* **Return structured data:** JSON or other machine-readable formats work best for programmatic processing

1455* **Keep responses concise:** Return only necessary data to minimize processing overhead

1453* **Provide detailed output descriptions:** Because Claude deserializes tool results in code, document the format (JSON structure and field types).

1454* **Return structured data:** JSON or other machine-readable formats work best for programmatic processing.

1455* **Keep responses concise:** Return only necessary data to minimize processing overhead.

14561456

14571457### When to use programmatic calling

14581458

1459Programmatic tool calling trades a small fixed overhead (container startup, script generation) for large savings on tool-result tokens and model round-trips. Whether that trade pays off depends on workload shape.

14601460

14611461**Strong fit:**

14621462

from line 1474

14741474

14751475### Performance optimization

14761476

1477* **Reuse containers** when making multiple related requests to maintain state

1478* **Batch similar operations** in a single code execution when possible

1477* **Reuse containers** when making multiple related requests to maintain state.

1478* **Batch similar operations** in a single code execution when possible.

14791479

14801480## Troubleshooting

14811481

from line 1483

14831483

14841484**`invalid_request_error` when setting `tool_choice`**

14851485

1486* `tool_choice` cannot name a tool whose `allowed_callers` omits `"direct"`. Either add `"direct"` to that tool's `allowed_callers`, or remove the tool from `tool_choice` and let Claude invoke it from code.

14871487

14881488**Container expiration**

14891489

14901490* Respond to each programmatic tool call well before the paused response's `expires_at` timestamp. Claude's code stops waiting for a result after about 4 minutes, and idle containers are currently reclaimed after about 5 minutes.

1491* Consider implementing faster tool execution

1491* Consider implementing faster tool execution.

14921492

14931493**Tool result not parsed correctly**

14941494

1495* Ensure your tool returns string data that Claude can deserialize

1496* Provide clear output format documentation in your tool description

1495* Ensure your tool returns string data that Claude can deserialize.

1496* Provide clear output format documentation in your tool description.

14971497

14981498### Debugging tips

14991499

15001. **Log all tool calls and results** to track the flow

15012. **Check the `caller` field** to confirm programmatic invocation

15023. **Monitor container IDs** to ensure proper reuse

15034. **Test tools independently** before enabling programmatic calling

15001. **Log all tool calls and results** to track the flow.

15012. **Check the `caller` field** to confirm a programmatic call.

15023. **Monitor container IDs** to ensure proper reuse.

15034. **Test tools independently** before enabling programmatic calling.

15041504

15051505## Why programmatic tool calling works

15061506

15071507Claude is trained on large amounts of code, so presenting tools as callable Python functions lets it use that strength:

15081508

1509* **Tool composition:** Chained calls, loops, and conditionals are ordinary Python control flow instead of a series of model round trips

1510* **Result processing:** Claude's code filters and aggregates large tool outputs, or writes them to files, and only the final output enters the context window

1511* **Latency:** The model is not re-sampled between the tool calls inside one code execution

1509* **Tool composition:** Chained calls, loops, and conditionals are ordinary Python control flow instead of a series of model round trips.

1510* **Result processing:** Claude's code filters and aggregates large tool outputs, or writes them to files, and only the final output enters the context window.

1511* **Latency:** The model is not re-sampled between the tool calls inside one code execution.

15121512

15131513## Alternative implementations

15141514

from line 1516

15161516

15171517### Client-side direct execution

15181518

1519Provide Claude with a code execution tool and describe what functions are available in that environment. When Claude invokes the tool with code, your application executes it locally where those functions are defined.

1519Provide Claude with a code execution tool and describe what functions are available in that environment. When Claude calls the tool with code, your application runs it locally where those functions are defined.

15201520

15211521**Advantages:**

15221522

from line 1525

15251525

15261526**Disadvantages:**

15271527

1528* Executes untrusted code outside of a sandbox

1529* Tool invocations can be vectors for code injection

1528* Runs untrusted code outside of a sandbox

1529* Tool calls can be vectors for code injection

15301530

1531**Use when:** Your application can safely execute arbitrary code, you want the smallest implementation, and Anthropic's managed offering doesn't fit your needs.

1531**Use when:** Your application can safely run arbitrary code, you want the smallest implementation, and Anthropic's managed offering doesn't fit your needs.

15321532

15331533### Self-managed sandboxed execution

15341534

1535Same approach from Claude's perspective, but code runs in a sandboxed container with security restrictions (for example, no network egress). If your tools require external resources, you'll need a protocol for executing tool calls outside the sandbox.

15361536

15371537**Advantages:**

15381538

from line 1548

15481548

15491549### Anthropic-managed execution

15501550

1551Anthropic's programmatic tool calling is a managed version of sandboxed execution with an opinionated Python environment tuned for Claude. Anthropic handles container management, code execution, and secure tool invocation communication.

15521552

15531553**Advantages:**

15541554

from line 1572

15721572 </Card>

15731573

15741574 <Card title="Code execution tool" icon="code" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool">

1575 Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.

1575 Run Python and Bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.

15761576 </Card>

15771577

15781578 <Card title="Tool use with Claude" icon="wrench" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview">

1579 Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.

1579 Connect Claude to external tools and APIs. See where tools run, when Claude calls them, and which tool fits your task.

15801580 </Card>

15811581

15821582 <Card title="Define tools" icon="hammer" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools">

This page’s history 14 edits

22 Oct 2026 +8 −8
21 Oct 2026 +1 −1
21 Oct 2026 +80 −80 · this one
21 Oct 2026 +10 −14
9 Oct 2026 +0 −2
7 Oct 2026 +2 −1

The page’s own history →

Where it came from

The captureapi
Upstream pageplatform.claude.com

Around it

Every changethe ledger
That day21 Oct 2026