> ## 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.2 creating tools

# Creating Tools

Tools allow your agents to execute Python code, access external systems, and perform actions that language models cannot do on their own.

In BindAI, creating a tool is intentionally simple: write a Python function and register it with an agent.

***

# The Simplest Tool

A tool is typically a normal Python function decorated with `@tool`.

```python theme={null}
from bindai_tools import tool

@tool
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

Once registered, the language model can decide when to call it.

***

# Registering a Tool

Register the tool on an agent.

```python theme={null}
agent.tool(
    greet,
)
```

The tool immediately becomes available during execution.

***

# Calling a Tool

Suppose the user asks:

```text theme={null}
Say hello to Alice.
```

The model may generate an internal tool call similar to:

```text theme={null}
greet(name="Alice")
```

BindAI executes the function automatically and returns:

```text theme={null}
Hello, Alice!
```

The model then uses that result to generate the final response.

***

# Tool Parameters

BindAI automatically discovers function parameters.

Example:

```python theme={null}
from bindai_tools import tool

@tool
def add(
    a: int,
    b: int,
) -> int:
    return a + b
```

The model understands that the tool expects:

* `a`
* `b`

Both are integers.

***

# Optional Parameters

Default values become optional parameters.

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

The model may call:

```text theme={null}
search(query="BindAI")
```

or

```text theme={null}
search(query="BindAI", limit=10)
```

***

# Type Hints

Always provide type hints.

Good:

```python theme={null}
@tool
def weather(
    city: str,
) -> str:
    ...
```

Avoid:

```python theme={null}
@tool
def weather(city):
    ...
```

Type hints improve parameter validation and help language models understand the expected inputs.

***

# Returning Values

Tools can return nearly any Python object.

Simple text:

```python theme={null}
@tool
def ping():
    return "Pong"
```

Numbers:

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

Lists:

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

Objects:

```python theme={null}
@tool
def profile():
    return {
        "name": "Alice",
        "age": 28,
    }
```

BindAI converts the output into a tool result that is passed back to the language model.

***

# Accessing External APIs

Tools are ideal for API integrations.

Example:

```python theme={null}
@tool
def get_weather(
    city: str,
):
    # call weather API
    ...
```

The agent can now answer questions using live information instead of relying only on model knowledge.

***

# Reading Files

Tools can interact with the file system.

```python theme={null}
@tool
def read_file(
    path: str,
):
    with open(path) as file:
        return file.read()
```

This enables document analysis and automation workflows.

***

# Database Queries

Tools can access databases.

```python theme={null}
@tool
def customer(
    customer_id: int,
):
    ...
```

Agents can retrieve records, perform lookups, or execute business operations.

***

# Using Multiple Tools

Register as many tools as needed.

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

agent.tool(weather)

agent.tool(calculate)
```

During execution, the language model chooses the most appropriate tool.

***

# Tool Descriptions

Provide meaningful names and documentation.

Example:

```python theme={null}
@tool
def exchange_rate(
    from_currency: str,
    to_currency: str,
):
    """
    Returns the latest exchange rate.
    """
```

Descriptions help the model decide when a tool should be used.

***

# Tool Context

Advanced tools may receive an execution context.

The context can expose:

* workflow variables
* runtime state
* metadata
* execution information

This allows tools to participate in larger workflows without requiring additional parameters.

***

# Error Handling

Handle expected failures inside the tool.

Example:

```python theme={null}
@tool
def read_file(
    path: str,
):
    try:
        with open(path) as file:
            return file.read()
    except FileNotFoundError:
        return "File not found."
```

Returning useful information is generally better than allowing the tool to fail unexpectedly.

***

# Tool Result Flow

```text theme={null}
User

↓

Language Model

↓

Tool

↓

Tool Result

↓

Language Model

↓

Final Response
```

The language model never executes the Python function directly. It only requests the tool; BindAI performs the execution.

***

# Best Practices

* Give tools descriptive names.
* Keep each tool focused on a single responsibility.
* Use type hints for every parameter.
* Return predictable outputs.
* Handle expected errors gracefully.
* Avoid unnecessary side effects.
* Write clear docstrings and descriptions.
* Reuse tools across multiple agents whenever possible.

***

# Example

```python theme={null}
from bindai_tools import tool

@tool
def multiply(
    a: int,
    b: int,
) -> int:
    """Multiply two numbers."""
    return a * b

agent.tool(
    multiply,
)
```

Now the agent can answer questions such as:

```text theme={null}
What is 14 × 9?
```

by calling the tool automatically.