Overview
This page is the atomic definition. The tool call that precedes this is defined at tool-call. Full tool-use patterns live at tool-use.
Definition
A tool result is the content returned to the LLM after a tool-call has been executed by the runtime. In the Anthropic API, when the model emits a tool_use block, the caller executes the tool and sends back a tool_result block with the same tool_use_id. The model then receives this result as a new observation in its context and decides whether to call another tool, revise its plan, or emit a final response. The structure of tool results matters: verbose or unstructured results consume context window and may confuse the model. Best practice is to return the minimum information the model needs, structured as JSON or a short text summary. Error results should include a clear error code and message so the model can decide whether to retry or escalate. Tool results in the agent-loop are the primary mechanism through which the model observes the world; their quality directly affects the model’s reasoning quality.
When it applies
Handle tool result formatting explicitly in every tool implementation. Truncate large outputs (e.g., file reads beyond a few kilobytes) to a summary plus a signal that the full content is available via a follow-up call. Never return raw stack traces or multi-megabyte blobs as tool results.
Example
Tool call: read_file(path="/src/app.py"). The runtime reads the file and returns:
{"tool_use_id": "tu_abc", "type": "tool_result", "content": "# app.py (truncated to 500 lines)\n...file content..."}The model uses this observation to decide the next step: call a code editing tool or ask for clarification.
Related concepts
- tool-call - the model’s request that generates this result.
- tool-use - the broader practice of equipping LLMs with external tools.
- agent-loop - tool results are the observation step in each loop iteration.
- function-calling - the equivalent mechanism in OpenAI’s API.
- hallucination - a model that hallucinates tool results skips the execution step, breaking the loop.
Citing this term
See Tool Result (llmbestpractices.com/glossary/tool-result).