Creating Tools

Tools are Python callables that agents can use during execution. They allow BindAI applications to perform operations such as:

Calling APIs
Querying databases
Reading files
Performing calculations
Executing business logic
Accessing external services

Creating a tool is intentionally simple: define a Python function and decorate it with @tool.

Your First Tool

The simplest tool is a decorated Python function.

from bindai import tool


@tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

The @tool decorator marks the function as a BindAI tool. The function remains normal Python code. BindAI adds the information needed for the function to participate in agent tool calling.

Registering a Tool

A tool can be registered with an agent using the builder API.

from bindai import Agent, tool


@tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .tool(greet)
    .build()
)

A tool can also be registered after the agent has been created:

agent.tool(greet)

Use the builder when tools are part of the initial agent configuration. Use agent.tool() when a tool needs to be attached to an existing agent.

Registering Multiple Tools

Use .tools() when an agent needs several capabilities.

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("Use the available tools when appropriate.")
    .tools(
        search,
        get_weather,
        calculate,
    )
    .build()
)

This allows the agent to expose several focused capabilities to the model.

Automatic Tool Calling

Once a tool is registered, the model can request it during agent execution when appropriate. For example:

@tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

A user might ask:

Say hello to Alice.

The model may decide to request the tool with an argument equivalent to:

greet(name="Alice")

BindAI then executes the registered function and makes its result available to the ongoing agent execution. The model can use that result when continuing the request.

Parameters

Tool parameters come directly from the Python function signature.

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

The function communicates that:

a is an integer
b is an integer
both parameters are required
the function returns an integer

Use clear parameter names and type annotations.

Optional Parameters

Python default values can be used for optional parameters.

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

The tool can be called with only the required parameter:

search(query="BindAI")

or with an explicit limit:

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

Defaults should be chosen carefully so that the tool behaves safely when optional values are omitted.

Type Hints

Type hints are strongly recommended for tools. Good:

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

Less descriptive:

@tool
def weather(city): ...

Type annotations make the tool interface explicit and provide useful information for tool schema generation and argument handling. Prefer annotations for:

Strings
Integers
Floats
Booleans
Collections
Structured application types

Keep complex tool interfaces understandable to both developers and models.

Docstrings

Give tools concise descriptions.

@tool
def exchange_rate(
    from_currency: str,
    to_currency: str,
) -> str:
    """Return the exchange rate between two currencies."""
    ...

A clear description helps communicate what the tool does and when it should be used. Avoid vague descriptions such as:

Do something.

Prefer descriptions that identify the operation and its purpose. A good tool description should make it clear:

What the tool does
When it should be used
What its important parameters represent
What kind of result it returns

Returning Values

Tools can return values produced by the underlying Python function.

Strings

@tool
def ping() -> str:
    return "Pong"

Numbers

@tool
def square(value: int) -> int:
    return value * value

Lists

@tool
def colors() -> list[str]:
    return [
        "red",
        "green",
        "blue",
    ]

Dictionaries

@tool
def profile() -> dict:
    return {
        "name": "Alice",
        "age": 28,
    }

The returned value becomes part of the tool output used by the agent execution. Prefer predictable, concise return values.

Returning Structured Data

Tools can return structured Python values when the application needs more than plain text. For example:

@tool
def get_profile() -> dict:
    return {
        "name": "Alice",
        "department": "Research",
        "active": True,
    }

Structured results can make it easier for the model and surrounding application logic to work with the returned information. Keep returned data focused on what the agent actually needs. Avoid returning large application objects, unnecessary metadata, credentials, or internal implementation details.

Calling APIs

Tools are useful for integrating external services. For example:

from urllib.request import Request, urlopen

from bindai import tool


@tool
def get_weather(city: str) -> str:
    """Get weather information for a city."""
    request = Request(
        f"https://example.com/weather/{city}",
        headers={"Accept": "application/json"},
    )

    with urlopen(request, timeout=10) as response:
        return response.read().decode("utf-8")

For production applications, consider:

Request timeouts
Authentication
Rate limits
API failures
Response validation
Retries where appropriate
Secure credential handling

Do not expose API credentials as tool parameters unless there is a specific, controlled reason to do so.

Reading Files

A tool can expose controlled file operations.

from pathlib import Path

from bindai import tool


@tool
def read_file(path: str) -> str:
    """Read an allowed text file."""
    return Path(path).read_text()

Be careful when exposing file-system operations to agents. Production applications should validate paths and restrict access to files the agent is allowed to read. Avoid giving an agent unrestricted access to the host file system.

Working with Databases

Database operations can also be exposed through tools.

from bindai import tool


@tool
def get_customer(customer_id: int):
    """Return customer information for a customer ID."""
    ...

Tools can provide controlled access to operations such as:

Querying records
Inserting data
Updating records
Looking up customers
Executing business operations

Keep database access behind well-defined functions rather than exposing unrestricted SQL execution to the model. For state-changing operations, validate parameters and apply the same authorization rules used by the rest of the application.

Multiple Tools

An agent can register multiple tools.

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .tools(
        search,
        get_weather,
        calculate,
    )
    .build()
)

The model can select the appropriate registered capability during execution. For example:

User
  |
  +-- Search request -----> search()
  |
  +-- Weather request ----> get_weather()
  |
  +-- Calculation --------> calculate()

Focused tools make this selection easier to understand and maintain.

Tool Execution

A typical tool-enabled execution looks like this:

User
  |
  v
Agent
  |
  v
Language Model
  |
  v
Tool Request
  |
  v
Python Function
  |
  v
Tool Result
  |
  v
Language Model
  |
  v
Final Response

The model can use the returned tool output when continuing the execution. An agent may perform more than one tool operation before producing its final response.

Tool Iterations

An agent execution can involve multiple rounds of tool calls. For example:

User
  |
  v
Model
  |
  v
Search Tool
  |
  v
Model
  |
  v
Calculator Tool
  |
  v
Model
  |
  v
Final Response

The execution system coordinates these interactions. Applications should not assume that a request will always involve exactly one tool call. If an application requires strict limits on execution or tool activity, configure and enforce those limits through the supported execution configuration for the BindAI version being used.

Error Handling

Tools should handle expected failures explicitly. For example:

from pathlib import Path

from bindai import tool


@tool
def read_file(path: str) -> str:
    """Read a text file."""
    try:
        return Path(path).read_text()
    except FileNotFoundError:
        return "File not found."

For external APIs and databases, handle expected operational failures in a similar way. Useful error handling should provide enough information for the application or agent to understand what happened without exposing unnecessary internal details.

Exceptions

Not every exception should be hidden. Unexpected programming errors should generally remain visible during development so they can be diagnosed and fixed. For expected operational failures, controlled handling may be appropriate. For example:

@tool
def divide(a: float, b: float):
    if b == 0:
        return "Division by zero is not allowed."

    return a / b

The exact error-handling strategy should depend on whether the failure is expected and recoverable. Do not silently convert every exception into a normal result. Doing so can make programming errors difficult to detect.

Tool Lifecycle

A typical tool-enabled execution follows this lifecycle:

Register Tool
      |
      v
Expose Tool
      |
      v
Model Chooses Tool
      |
      v
Execute Function
      |
      v
Return Tool Output
      |
      v
Continue Agent Execution
      |
      v
Final Response

The agent coordinates the interaction between the model and registered tools.

Tool Organization

As projects grow, keep tools separated by responsibility. For example:

tools/
├── weather.py
├── search.py
├── calculator.py
├── database.py
└── notifications.py

Each module can contain related tools. This makes tools easier to:

Discover
Test
Maintain
Reuse
Review for security

Avoid creating one large module containing unrelated application capabilities.

Tool Reuse

The same tool can be attached to multiple agents.

weather = get_weather

support_agent.tool(weather)
sales_agent.tool(weather)
research_agent.tool(weather)

This avoids duplicating implementations. When the shared tool’s behavior changes, every agent using that tool can receive the updated implementation. Shared tools should therefore have stable interfaces and well-defined behavior.

Tool Safety

Tools can perform real operations, so they should be treated as application boundaries. For sensitive operations:

Validate inputs.
Restrict accessible resources.
Avoid unrestricted file-system access.
Protect credentials.
Validate external API parameters.
Enforce authorization where appropriate.
Keep destructive operations narrowly scoped.
Avoid returning sensitive information to the model.
Require confirmation for high-impact actions where appropriate.

A language model should not automatically receive unrestricted access to an application. Security controls should remain enforced by the application and the systems behind the tool.

Read vs Write Tools

It is useful to distinguish between tools that read information and tools that modify state. Read-oriented tools might include:

search()
get_customer()
get_weather()

State-changing tools might include:

create_customer()
send_email()
update_record()
delete_document()

Write operations require additional care because they can change real application state. For sensitive or irreversible operations, consider:

Explicit authorization
Input validation
Confirmation
Idempotency
Audit logging
Narrow permissions

Do not rely on the model alone to decide whether a sensitive operation is safe.

Execution Context

Some advanced BindAI integrations may need execution context in addition to normal function arguments. For standard tools, prefer explicit function parameters:

@tool
def get_customer(customer_id: int): ...

This keeps the tool interface simple and predictable. When a tool genuinely requires runtime execution information, use the context mechanism supported by the relevant BindAI tool/execution API rather than relying on undocumented conventions.

Tools and External Integrations

Tools are a natural interface for external services. Examples include:

REST APIs
Databases
Search services
SaaS platforms
Internal business systems
Application services

For repeated integrations, BindAI’s Connections package provides a dedicated integration boundary. A common architecture is:

Agent
  |
  v
Tool
  |
  v
Connection
  |
  v
External Service

The tool can expose a focused operation while the connection handles communication with the external service. This keeps integration details separate from the agent’s high-level behavior.

Tool Testing

Tools should be tested independently from the language model whenever possible. A deterministic tool can be tested like normal Python application code:

def multiply(a: int, b: int) -> int:
    return a * b


assert multiply(2, 3) == 6

Tool integration tests can then verify that the tool is correctly registered with an agent. Useful test areas include:

Tool registration
Parameter handling
Successful execution
Error handling
External service failures
Security and authorization
Tool output formatting

Keeping tool logic independently testable makes agent behavior easier to debug.

Tool Calling Across Providers

Tool calling is coordinated between BindAI and the selected model provider. The provider determines how tool calls are represented to the model, while BindAI manages application-level tool execution. This allows tool implementations to remain largely independent of a specific provider. Conceptually:

                 BindAI Agent
                      |
                      v
                Model Provider
                      |
                      v
                  Tool Call
                      |
                      v
                 BindAI Tool
                      |
                      v
                Python / API

This separation helps applications change providers without rewriting their core tool implementations.

Tools and Memory

Tools can work alongside BindAI memory. For example:

User
  |
  v
Agent
  |
  +---- Memory
  |
  +---- Tool
  |
  v
Response

Memory provides contextual information, while tools provide executable capabilities. The two mechanisms solve different problems and can be combined in the same agent.

Tools and Knowledge

Tools can also complement BindAI knowledge and retrieval capabilities. For example:

Agent
  |
  +---- Knowledge / Retrieval
  |
  +---- Search Tool
  |
  +---- External API Tool
  |
  v
Final Response

Knowledge systems are useful for retrieving information from indexed content. Tools are useful when the agent needs to execute an operation or access a live external system.

Tools and Workflows

Tools can participate in workflow-driven applications. A workflow can coordinate agent execution while tools provide individual capabilities. Conceptually:

Workflow
   |
   v
Agent
   |
   +---- Tool A
   |
   +---- Tool B
   |
   +---- Tool C
   |
   v
Next Workflow Step

Use tools for individual operations and workflows for larger orchestration logic. Avoid putting complex multi-step orchestration directly inside a single tool.

Tools and Multi-Agent Systems

Tools can be assigned to different specialist agents. For example:

                 Team
                  |
        +---------+---------+
        |         |         |
        v         v         v
    Research    Support   Operations
       |           |         |
    Search       CRM       APIs
    Tools        Tools     Tools

Each specialist can expose the tools relevant to its role. Keeping tool sets focused can make multi-agent systems easier to reason about and maintain.

Tool Security Boundaries

A tool should define a clear boundary between model-generated requests and trusted application operations. For example:

Model-generated arguments
          |
          v
     Tool Boundary
          |
          +---- Validate
          |
          +---- Authorize
          |
          +---- Execute
          |
          v
    External System

The model supplies intent and arguments, but the application remains responsible for deciding whether the operation is allowed. This is especially important for:

Payments
Account changes
Deletions
Messaging
Database writes
File operations
Administrative actions

Complete Example

from bindai import Agent, tool


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


agent = (
    Agent.builder()
    .name("calculator")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant. Use the multiply tool when arithmetic is required.")
    .tool(multiply)
    .build()
)

result = agent.run("What is 14 × 9?")

if result.success:
    print(result.output)
else:
    print(result.error)

The agent has access to the multiply tool during execution and can use it when appropriate.

Best Practices

Keep each tool focused on one responsibility.
Use descriptive function and parameter names.
Add Python type hints.
Write concise and accurate docstrings.
Return predictable values.
Handle expected failures gracefully.
Allow unexpected programming errors to remain visible during development.
Validate inputs to external systems.
Restrict sensitive operations.
Protect credentials.
Avoid unnecessary side effects.
Keep long-running operations out of latency-sensitive paths when possible.
Reuse tools across multiple agents.
Prefer several focused tools over one large tool.
Test tools independently from the language model.
Apply authorization in application code.
Use dedicated connections for reusable external integrations.
Use workflows for complex orchestration.
Keep the model outside the application’s security boundary.

Summary

Creating a BindAI tool requires very little code:

from bindai import tool


@tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

agent.tool(greet)

or configure it with the builder:

agent = Agent.builder().tools(greet).build()

Once registered, the tool becomes a capability available during agent execution. Tools provide the bridge between language-model reasoning and deterministic application code, external services, and real-world operations. The most important design principle is to keep that bridge focused, testable, predictable, and secure.

​Creating Tools

​Your First Tool

​Registering a Tool

​Registering Multiple Tools

​Automatic Tool Calling

​Parameters

​Optional Parameters

​Type Hints

​Docstrings

​Returning Values

​Strings

​Numbers

​Lists

​Dictionaries

​Returning Structured Data

​Calling APIs

​Reading Files

​Working with Databases

​Multiple Tools

​Tool Execution

​Tool Iterations

​Error Handling

​Exceptions

​Tool Lifecycle

​Tool Organization

​Tool Reuse

​Tool Safety

​Read vs Write Tools

​Execution Context

​Tools and External Integrations

​Tool Testing

​Tool Calling Across Providers

​Tools and Memory

​Tools and Knowledge

​Tools and Workflows

​Tools and Multi-Agent Systems

​Tool Security Boundaries

​Complete Example

​Best Practices

​Summary