LLM Best Practices

Tool Result

2 min read

View markdown source

Overview

What goes back to the model after execution shapes its next step, so return concise, structured results and explicit error text instead of stack traces. The request side is tool-call; the full loop is in 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.

Citing this term

See Tool Result (llmbestpractices.com/glossary/tool-result).

  • 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.
  • system-message

Backlinks