Tool Result

What is a tool result?

A tool result is the output returned after an AI agent’s requested tool has been executed. It can contain retrieved data, a confirmation, a failure message, validation details, or a status showing that work is incomplete.

The result gives the agent evidence about what actually happened after its proposed action.

What a good result contains

A useful tool result should make its state explicit. Depending on the operation, it may include:

• whether execution succeeded, failed, or partially completed;
• the requested data or changed record identifier;
• structured error type and explanation;
• retry guidance when appropriate;
• source and timestamp information;
• details needed to confirm the resulting external state.

For example, an email tool should distinguish “draft created,” “message sent,” and “send request rejected.” Treating those outcomes as the same could make an agent incorrectly tell the user that delivery occurred.

Tool result versus observation

A tool result is the raw or structured output from the execution layer. An [observation](/glossary/observation/) is the information the agent receives and uses from the environment. In simple systems, the complete result becomes the observation. In other systems, software filters, validates, summarizes, or redacts it first.

A result is also different from the model’s expectation. The agent may predict success, but only the execution response and, when needed, a follow-up check can confirm the outcome.

How results affect the agent loop

After receiving a result, the agent updates its state and decides whether to continue. A successful search may provide the facts needed for a final answer. An empty result may require a revised query. A permission error may require user authorization. A timeout may be safe to retry, while an uncertain write may require checking whether the change already occurred.

Common failure modes

Unstructured or ambiguous results are difficult for models to interpret. Huge raw payloads waste context and can hide the relevant fields. Tool output may also contain untrusted content that attempts to redirect the agent.

Builders should use stable structured formats, separate data from instructions, preserve meaningful error codes, and avoid exposing sensitive fields unnecessarily.

Why it matters

Tool results close the gap between intended action and external reality. An agent that handles them well can adapt, recover, and report accurate status. One that assumes success may repeat actions, lose data, or mislead users.

Reliable systems design results as carefully as tool inputs and make success, failure, partial progress, and uncertainty distinct. See [Tool Use in AI Agents](/tool-use-in-ai-agents/) for the full call, execution, observation, and retry cycle.