> ## 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.1 overview

# Tools Overview

Tools allow BindAI agents to interact with the outside world.

Instead of relying solely on a language model, an agent can execute Python functions, query databases, call APIs, search documents, perform calculations, or integrate with third-party services.

Tools are one of the core building blocks of agentic applications.

***

# What is a Tool?

A tool is an executable function that an AI model can call during an agent execution.

Typical examples include:

* searching the web
* querying a database
* reading files
* sending emails
* performing calculations
* interacting with business systems
* retrieving knowledge

The language model decides **when** a tool should be used, while BindAI executes it safely and returns the result back to the model.

***

# Tool Execution Flow

```text id="2rk2cg" theme={null}
User

↓

Agent

↓

Language Model

↓

Tool Request

↓

Tool Execution

↓

Tool Result

↓

Language Model

↓

Final Response
```

This process is automatic once tools are registered with an agent.

***

# Why Use Tools?

Language models are limited to the information available in their context window and training data.

Tools allow agents to:

* access real-time information
* retrieve external knowledge
* execute business logic
* automate repetitive tasks
* interact with other applications
* perform deterministic operations

Without tools, agents can only generate text.

***

# Creating a Tool

A tool is usually implemented as a Python function.

Example:

```python id="r4ht9n" theme={null}
from bindai_tools import tool

@tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."
```

Once decorated, the function becomes available to agents.

***

# Registering Tools

Tools are registered on an agent.

```python id="g9mu8k" theme={null}
agent.tool(
    get_weather,
)
```

Multiple tools can be added.

```python id="k3tv2m" theme={null}
agent.tool(search)

agent.tool(get_weather)

agent.tool(calculate)
```

The agent automatically exposes them to the language model.

***

# Tool Discovery

During execution, BindAI converts registered tools into provider-compatible tool definitions.

The language model receives information such as:

* tool name
* description
* parameters
* parameter types

The model decides which tool should be called.

***

# Automatic Tool Calling

Example conversation:

```text id="3a4evx" theme={null}
User

↓

"What is the weather in Tokyo?"

↓

Model requests get_weather()

↓

Tool executes

↓

Model receives result

↓

Final answer
```

No manual tool invocation is required.

***

# Tool Parameters

Tool parameters are automatically exposed to the language model.

Example:

```python id="q8pd6w" theme={null}
@tool
def search(
    query: str,
    limit: int = 5,
):
    ...
```

The model generates:

```text id="2rpk9q" theme={null}
search(
    query="BindAI",
    limit=5
)
```

BindAI converts those arguments into Python values before execution.

***

# Tool Results

Every tool returns a result object.

Example:

```python id="x7jl1a" theme={null}
ToolResult(
    success=True,
    output="..."
)
```

The output is inserted back into the conversation so the model can continue reasoning.

***

# Multiple Tool Calls

Agents may call several tools during one execution.

```text id="66bjlwm" theme={null}
Search

↓

Database

↓

Calculator

↓

Final Answer
```

BindAI manages the execution loop automatically.

***

# Tool Categories

Typical tool categories include:

* Search
* APIs
* Databases
* File System
* Email
* Calendar
* Knowledge Retrieval
* AI Services
* Business Systems

Applications can combine tools from multiple categories.

***

# Shared Tools

Projects can expose shared tools.

```python id="nyh9e6" theme={null}
project.add_tool(
    search_tool,
)
```

Multiple agents inside the project can then use the same implementation.

***

# Tool Context

Every tool receives an execution context.

The context may include:

* variables
* workflow state
* metadata
* runtime information

This allows tools to access information beyond their input parameters.

***

# Tool Validation

BindAI validates tool parameters before execution.

Benefits include:

* correct data types
* required parameters
* predictable execution
* provider-independent behavior

***

# Tool Errors

If a tool fails, BindAI captures the error.

Example:

```python id="mv3swr" theme={null}
ToolResult(
    success=False,
    error="Database unavailable."
)
```

The language model can often recover by selecting another tool or responding appropriately.

***

# Best Practices

* Design tools to perform one clear task.
* Keep tool descriptions concise and descriptive.
* Use explicit parameter names.
* Return deterministic outputs whenever possible.
* Handle failures gracefully.
* Avoid long-running blocking operations unless necessary.
* Reuse shared tools across agents.

***

# Summary

Tools extend language models with real-world capabilities.

They allow agents to retrieve information, execute code, automate workflows, and interact with external systems while keeping the execution process consistent and provider-independent.