> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 03.4 tool results

# Tool Results

Every tool execution in BindAI produces a **Tool Result**.

A Tool Result represents the outcome of a tool invocation and provides a consistent interface for successful executions, failures, and returned data.

Instead of interacting directly with raw Python return values, the execution pipeline works with tool results.

***

# Why Tool Results?

Tool Results provide a standard format for tool execution.

Benefits include:

* consistent execution behavior
* predictable error handling
* provider-independent integration
* workflow compatibility
* easier debugging

Every tool execution follows the same lifecycle regardless of what the tool actually does.

***

# Successful Execution

When a tool completes successfully, its output becomes available to the execution pipeline.

Example:

```python id="u8f3mw" theme={null}
@tool
def multiply(
    a: int,
    b: int,
):
    return a * b
```

Calling:

```text id="f5g8zt" theme={null}
multiply(6, 7)
```

Produces a successful tool result containing:

* success status
* output value

***

# Failed Execution

If a tool cannot complete its task, the result contains an error instead of an output.

Example:

```python id="m9e2kr" theme={null}
@tool
def read_file(
    path: str,
):
    raise FileNotFoundError()
```

The execution engine captures the failure and reports it as a tool result rather than crashing the workflow.

***

# Result Structure

Conceptually, a Tool Result contains:

```text id="x7n4kd" theme={null}
success

output

error
```

Only one of **output** or **error** is typically populated.

***

# Successful Result

Example:

```text id="6jpw9m" theme={null}
success = True

output = "Customer found."

error = None
```

The language model receives the output and continues reasoning.

***

# Failed Result

Example:

```text id="e2vy7p" theme={null}
success = False

output = None

error = "Customer not found."
```

The language model may decide to:

* retry
* call another tool
* explain the error to the user

***

# Returning Objects

Tools may return structured Python objects.

Example:

```python id="z8aw6f" theme={null}
@tool
def customer():
    return {
        "id": 1001,
        "name": "Alice",
        "active": True,
    }
```

The execution pipeline preserves the returned value before making it available to later steps.

***

# Returning Lists

Lists are also supported.

```python id="j4vq1k" theme={null}
@tool
def colors():
    return [
        "red",
        "green",
        "blue",
    ]
```

The returned collection becomes the tool output.

***

# Returning Numbers

Simple values work naturally.

```python id="v9hg3u" theme={null}
@tool
def square(
    value: int,
):
    return value * value
```

The output is passed back without additional work.

***

# Using Tool Results in Workflows

Workflow nodes can store tool outputs as variables.

```text id="y5o7bl" theme={null}
Search Customer

↓

customer

↓

Generate Invoice

↓

Send Email
```

Each step consumes the result produced by the previous one.

***

# Using Tool Results in Agents

Agents receive tool outputs automatically.

Example:

```text id="lf6n4q" theme={null}
User

↓

Language Model

↓

Tool

↓

Tool Result

↓

Language Model

↓

Final Response
```

The model reasons over the returned information before producing the final answer.

***

# Error Recovery

Tool Results make recovery straightforward.

Instead of terminating execution immediately, BindAI can:

* retry the tool
* execute an alternative tool
* continue the workflow
* return a graceful error message

This behavior integrates well with retry and workflow policies.

***

# Logging

Tool Results are also useful for logging.

Typical information includes:

* execution time
* success or failure
* returned output
* error details

This simplifies debugging and monitoring.

***

# Best Practices

* Return clear, predictable values.
* Prefer structured objects for complex data.
* Keep outputs reasonably small.
* Handle expected failures inside the tool.
* Let unexpected exceptions surface when appropriate.
* Write tools that produce deterministic results whenever possible.

***

# Summary

Tool Results provide a consistent contract between tools, agents, and workflows.

Every execution produces either a successful output or an error, allowing BindAI to orchestrate tool usage, recover from failures, and keep execution behavior predictable across different providers and applications.