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:

@tool
def multiply(
    a: int,
    b: int,
):
    return a * b

Calling:

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:

@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:

success

output

error

Only one of output or error is typically populated.

---

Successful Result

Example:

success = True

output = "Customer found."

error = None

The language model receives the output and continues reasoning.

---

Failed Result

Example:

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:

@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.

@tool
def colors():
    return [
        "red",
        "green",
        "blue",
    ]

The returned collection becomes the tool output.

---

Returning Numbers

Simple values work naturally.

@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.

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:

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.