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.

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

agent.tool(
    greet,
)

The tool immediately becomes available during execution.

Calling a Tool

Suppose the user asks:

Say hello to Alice.

The model may generate an internal tool call similar to:

greet(name="Alice")

BindAI executes the function automatically and returns:

Hello, Alice!

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

Tool Parameters

BindAI automatically discovers function parameters. Example:

from bindai_tools import tool

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

The model understands that the tool expects:

Both are integers.

Optional Parameters

Default values become optional parameters.

@tool
def search(
    query: str,
    limit: int = 5,
):
    ...

The model may call:

search(query="BindAI")

search(query="BindAI", limit=10)

Type Hints

Always provide type hints. Good:

@tool
def weather(
    city: str,
) -> str:
    ...

Avoid:

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

@tool
def ping():
    return "Pong"

Numbers:

@tool
def square(
    value: int,
):
    return value * value

Lists:

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

Objects:

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

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

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

@tool
def customer(
    customer_id: int,
):
    ...

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

Using Multiple Tools

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:

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

@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

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

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:

What is 14 × 9?

by calling the tool automatically.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

API Reference

03.2 creating tools

Creating Tools

The Simplest Tool

Registering a Tool

Calling a Tool

Tool Parameters

Optional Parameters

Type Hints

Returning Values

Accessing External APIs

Reading Files

Database Queries

Using Multiple Tools

Tool Descriptions

Tool Context

Error Handling

Tool Result Flow

Best Practices

Example

​Creating Tools

​The Simplest Tool

​Registering a Tool

​Calling a Tool

​Tool Parameters

​Optional Parameters

​Type Hints

​Returning Values

​Accessing External APIs

​Reading Files

​Database Queries

​Using Multiple Tools

​Tool Descriptions

​Tool Context

​Error Handling

​Tool Result Flow

​Best Practices

​Example

Creating Tools

The Simplest Tool

Registering a Tool

Calling a Tool

Tool Parameters

Optional Parameters

Type Hints

Returning Values

Accessing External APIs

Reading Files

Database Queries

Using Multiple Tools

Tool Descriptions

Tool Context

Error Handling

Tool Result Flow

Best Practices

Example