handle-tool-calls changedagents-and-tools/tool-use/handle-tool-calls
Nearest release: v2.1.318, 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+41added
Lines−39removed
From line
57
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits8to this page, all time
The whole hunk
from line 57, old and new numbered
/
from line 57
5757 * `content` (optional): The result of the tool, as a string (for example, `"content": "15 degrees"`), a list of nested content blocks (for example, `"content": [{"type": "text", "text": "15 degrees"}]`), or a list of document blocks (for example, `"content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]`). These content blocks can use the `text`, `image`, `document`, or [`search_result`](https://platform.claude.com/docs/en/build-with-claude/search-results) types.
5858 * `is_error` (optional): Set to `true` if the tool execution resulted in an error.
5959
60For example, a successful tool result looks like this:
61
62```json JSON
63{
64 "role": "user",
65 "content": [
66 {
67 "type": "tool_result",
68 "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
69 "content": "15 degrees"
70 }
71 ]
72}
73```
74
6075A `tool_result` that answers a computer use or browser use member block must also echo the same `toolset_name` value as the `tool_use` block; a member result that omits it is rejected. Its `content` is also narrower: a member result may contain only `text` and `image` blocks, and a browser use result may add one [`browser_state`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) block (the [tab-management members](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#tab-management-results) return only that block).
6176
6277<Note>
from line 81
6681 * In the user message containing tool results, the `tool_result` blocks must come FIRST in the content array. Any text must come AFTER all tool results.
6782 * If the assistant turn also called a [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) that has no result block yet, the user message must contain only `tool_result` blocks. Text after the results ends the turn early; for a server tool Claude called directly, the request then fails with a 400 error that names the unresolved server tool. See [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#tool-use).
6883
69 For example, this causes a 400 error:
70
71 ```json
72 {
73 "role": "user",
74 "content": [
75 { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
76 { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
77 ]
78 }
79 ```
80
81 This is correct when the assistant turn calls only client tools:
82
83 ```json
84 {
85 "role": "user",
86 "content": [
87 { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
88 { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
89 ]
90 }
91 ```
92
9384 If you receive an error such as “tool\_use ids were found without tool\_result blocks immediately after”, check that your tool results are formatted correctly.
9485</Note>
9586
from line 89
9889</Warning>
9990
10091<AccordionGroup>
101 <Accordion title="Example of successful tool result">
102 ```json JSON
103 {
104 "role": "user",
105 "content": [
106 {
107 "type": "tool_result",
108 "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
109 "content": "15 degrees"
110 }
111 ]
112 }
113 ```
114 </Accordion>
115
11692 <Accordion title="Example of tool result with images">
11793 ```json JSON
11894 {
from line 148
172148 }
173149 ]
174150 }
151 ]
152 }
153 ```
154 </Accordion>
155
156 <Accordion title="Example of text before and after a tool result">
157 For example, this causes a 400 error:
158
159 ```json
160 {
161 "role": "user",
162 "content": [
163 { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
164 { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
165 ]
166 }
167 ```
168
169 This is correct when the assistant turn calls only client tools:
170
171 ```json
172 {
173 "role": "user",
174 "content": [
175 { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
176 { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
175177 ]
176178 }
177179 ```
No line in this hunk matches that.