Process results programmatically changedagents-and-tools/tool-use/programmatic-tool-calling
Nearest release: v2.1.309, published 13 hours 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+9added
Lines−9removed
From line
368
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits18to this page, all time
The whole hunk
from line 368, old and new numbered
/
from line 368
368368
369369When you configure a tool to be callable from code execution and Claude determines that tool is needed:
370370
3711. Claude writes Python code that calls the tool as a function. The code can include multiple tool calls and pre/post-processing logic.
3711. Claude writes Python code that calls the tool as a function. The code can include multiple tool calls, plus preprocessing and post-processing logic.
3723722. Claude runs this code in a sandboxed container through code execution.
3733733. When a tool function is called, code execution pauses and the API returns a `tool_use` block.
3743744. You provide the tool result, and code execution continues (intermediate results are not loaded into Claude's context window).
from line 423
423423
424424**Direct call (traditional tool use):**
425425
426```text wrap
426```json
427427{
428428 "type": "tool_use",
429429 "id": "toolu_abc123",
from line 435
435435
436436**Programmatic call:**
437437
438```text wrap
438```json
439439{
440440 "type": "tool_use",
441441 "id": "toolu_xyz789",
from line 481
481481
482482Claude writes code that calls your tool. The API pauses and returns:
483483
484```text Output
484```json Output
485485{
486486 "role": "assistant",
487487 "content": [
from line 1143
11431143
11441144### Step 4: Next tool call or completion
11451145
1146The code picks up where it paused and processes your result. Each continuation response either pauses again with more programmatic `tool_use` blocks, or completes the code execution and lets Claude continue the turn (Step 5). Check `stop_reason` and each `tool_use` block's `caller` to tell the two apart: a response that pauses for you has `stop_reason: "tool_use"` and a `tool_use` block whose `caller` names a code execution version, and you repeat Step 3 with a `tool_result` for every pending programmatic call in one user message.
1146The code picks up where it paused and processes your result. Each continuation response either pauses again with more programmatic `tool_use` blocks, or completes the code execution and lets Claude continue the turn (Step 5). Check `stop_reason` and each `tool_use` block's `caller` to tell the two apart. A response that pauses for you has `stop_reason: "tool_use"` and a `tool_use` block whose `caller` names a code execution version. In that case, repeat Step 3 with a `tool_result` for every pending programmatic call in one user message.
11471147
11481148### Step 5: Final response
11491149
11501150Once the code execution completes, Claude provides the final response:
11511151
1152```text Output
1152```json Output
11531153{
11541154 "content": [
11551155 {
from line 1238
12381238
12391239When code execution calls a tool:
12401240
1241```text wrap
1241```json
12421242{
12431243 "type": "tool_use",
12441244 "id": "toolu_abc123",
from line 1272
12721272
12731273When all tool calls are satisfied and code completes:
12741274
1275```text
1275```json
12761276{
12771277 "type": "code_execution_tool_result",
12781278 "tool_use_id": "srvtoolu_xyz789",
from line 1299
12991299
13001300If 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:
13011301
1302```text
1302```json
13031303{
13041304 "type": "code_execution_tool_result",
13051305 "tool_use_id": "srvtoolu_abc123",
No line in this hunk matches that.