handle-tool-calls changedagents-and-tools/tool-use/handle-tool-calls
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
Lines+19added
Lines−19removed
From line
14
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits5to this page, all time
The whole hunk
from line 14, old and new numbered
/
from line 14
1414
1515## Handling results from client tools
1616
17The response will have a `stop_reason` of `tool_use` and one or more `tool_use` content blocks that include:
17The response has a `stop_reason` of `tool_use` and one or more `tool_use` content blocks that include:
1818
19* `id`: A unique identifier for this particular tool use block. This will be used to match up the tool results later.
19* `id`: A unique identifier for this particular tool use block. This is used to match up the tool results later.
2020* `name`: The name of the tool being used.
2121* `input`: An object containing the input being passed to the tool, conforming to the tool's `input_schema`.
2222
from line 49
4949
50501. Extract the `name`, `id`, and `input` from the `tool_use` block.
5151
522. Run the actual tool in your codebase corresponding to that tool name, passing in the tool `input`.
522. Run the actual tool in your code base corresponding to that tool name, passing in the tool `input`.
5353
54543. Continue the conversation by sending a new message with the `role` of `user`, and a `content` block containing the `tool_result` type and the following information:
5555
from line 63
6363 **Important formatting requirements:**
6464
6565 * Tool result blocks must immediately follow their corresponding tool use blocks in the message history. You cannot include any messages between the assistant's tool use message and the user's tool result message.
66 * 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.
66 * 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.
6767 * 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).
6868
69 For example, this will cause a 400 error:
69 For example, this causes a 400 error:
7070
7171 ```json
7272 {
from line 90
9090 }
9191 ```
9292
93 If you receive an error like "tool\_use ids were found without tool\_result blocks immediately after", check that your tool results are formatted correctly.
93 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.
9494</Note>
9595
9696<Warning>
97 Tool results often carry content from sources outside your control: web pages, inbound email, user uploads, third-party APIs. Treat that content as untrusted: an attacker who can influence it may embed instructions that try to redirect Claude (indirect prompt injection). Keep untrusted content inside `tool_result` blocks rather than `system` prompts or plain user `text` blocks, and see [Mitigate jailbreaks and prompt injections](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) for further hardening.
97 Tool results often carry content from sources outside your control: webpages, inbound email, user uploads, third-party APIs. Treat that content as untrusted: an attacker who can influence it might embed instructions that try to redirect Claude (indirect prompt injection). Keep untrusted content inside `tool_result` blocks rather than `system` prompts or plain user `text` blocks, and see [Mitigate jailbreaks and prompt injections](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) for further hardening.
9898</Warning>
9999
100100<AccordionGroup>
from line 182
182182
183183## Handling results from server tools
184184
185Claude executes the tool internally and incorporates the results directly into its response without requiring additional user interaction.
185Claude runs the tool internally and incorporates the results directly into its response without requiring additional user interaction.
186186
187187<Note>
188 A response can contain both a client `tool_use` block and a `server_tool_use` block that has no result block. That server tool call is not finished yet, and its result block arrives in a later response. Reply with a user message that contains only the `tool_result` blocks for the client tools and keep the same `tools` array; for a server tool Claude called directly, the API runs it on that request and the next response starts with its result block. See [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#tool-use).
188 A response can contain both a client `tool_use` block and a `server_tool_use` block that has no result block. That server tool call is not complete yet, and its result block arrives in a later response. Reply with a user message that contains only the `tool_result` blocks for the client tools and keep the same `tools` array; for a server tool Claude called directly, the API runs it on that request and the next response starts with its result block. See [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#tool-use).
189189</Note>
190190
191191<Tip>
from line 193
193193
194194 Unlike APIs that separate tool use or use special roles like `tool` or `function`, the Claude API integrates tools directly into the `user` and `assistant` message structure.
195195
196 Messages contain arrays of `text`, `image`, `tool_use`, and `tool_result` blocks. `user` messages include client content and `tool_result`, while `assistant` messages contain AI-generated content and `tool_use`.
196 Messages contain arrays of `text`, `image`, `tool_use`, and `tool_result` blocks. `user` messages include client content and `tool_result`, whereas `assistant` messages contain AI-generated content and `tool_use`.
197197</Tip>
198198
199199## Handling errors with is\_error
from line 221
221221 Claude will then incorporate this error into its response to the user. For example: "I'm sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later."
222222
223223 <Tip>
224 Write instructive error messages. Instead of generic errors like `"failed"`, include what went wrong and what Claude should try next (for example, `"Rate limit exceeded. Retry after 60 seconds."`). This gives Claude the context it needs to recover or adapt without guessing.
224 Write instructive error messages. Instead of generic errors such as `"failed"`, include what went wrong and what Claude should try next (for example, `"Rate limit exceeded. Retry after 60 seconds."`). This gives Claude the context it needs to recover or adapt without guessing.
225225 </Tip>
226226 </Accordion>
227227
228228 <Accordion title="Invalid tool name">
229 If Claude's attempted use of a tool is invalid (for example, missing required parameters), it usually means that there wasn't enough information for Claude to use the tool correctly. Your best bet during development is to try the request again with more-detailed `description` values in your tool definitions.
229 If Claude's attempted use of a tool is invalid (for example, missing required parameters), it usually means that there wasn't enough information for Claude to use the tool correctly. The best approach during development is to try the request again with more-detailed `description` values in your tool definitions.
230230
231 However, you can also continue the conversation forward with a `tool_result` that indicates the error, and Claude will try to use the tool again with the missing information filled in:
231 However, you can also continue the conversation forward with a `tool_result` that indicates the error, and Claude will attempt to use the tool again with the missing information filled in:
232232
233233 ```json JSON
234234 {
from line 244
244244 }
245245 ```
246246
247 If a tool request is invalid or missing parameters, Claude will retry 2-3 times with corrections before apologizing to the user.
247 If a tool request is invalid or missing parameters, Claude will retry 2–3 times with corrections before apologizing to the user.
248248
249249 <Tip>
250 To eliminate invalid tool calls entirely, use [strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use) with `strict: true` on your tool definitions. This guarantees that tool inputs will always match your schema exactly, preventing missing parameters and type mismatches.
250 To eliminate invalid tool calls entirely, use [strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use) with `strict: true` on your tool definitions. This guarantees that tool inputs always match your schema exactly, preventing missing parameters and type mismatches.
251251 </Tip>
252252 </Accordion>
253253
254254 <Accordion title="Server tool errors">
255 When server tools encounter errors (for example, network issues with Web Search), Claude will transparently handle these errors and attempt to provide an alternative response or explanation to the user. Unlike client tools, you do not need to handle `is_error` results for server tools.
255 When server tools encounter errors (for example, network issues with web search), Claude will transparently handle these errors and attempt to provide an alternative response or explanation to the user. Unlike client tools, you do not need to handle `is_error` results for server tools.
256256
257257 For web search specifically, possible error codes include:
258258
from line 271
271271 Handle responses where Claude calls several tools in a single turn.
272272 </Card>
273273
274 <Card title="Tool Runner (SDK)" icon="wrench" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner">
274 <Card title="Tool runner (SDK)" icon="wrench" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner">
275275 Let the SDK manage the `tool_use` loop, result formatting, and retries for you.
276276 </Card>
277277
No line in this hunk matches that.