Tools Overview

Tools give BindAI applications a way to expose executable capabilities to agents and workflows. A tool can wrap application logic such as:

Calculations
Data processing
API calls
Business logic
Project-specific operations
External integrations

In BindAI V1, tools are implemented as Python callables or Tool objects and can be registered in a ToolRegistry. Project tools can then be discovered by the Studio runtime and used by workflow Tool nodes.

What Is a Tool?

A BindAI tool represents an executable operation. The simplest way to create a project tool is with the @tool decorator:

from bindai_tool import tool


@tool
def echo(text: str) -> str:
    return text

The decorated function becomes a BindAI tool that can be registered and executed through the tool system. Python type annotations should be used for tool parameters because they make the tool interface explicit.

Creating Tools

Project tools are normally stored in the project’s tools directory. For example:

my-project/
├── agents/
├── tools/
│   ├── echo.py
│   └── increment.py
└── workflows/

A tool module can contain:

from bindai_tool import tool


@tool
def increment(value: int) -> int:
    return value + 1

Another example:

from bindai_tool import tool


@tool
def echo(text: str) -> str:
    return text

These functions can then be discovered by the project runtime.

Tool Definitions

BindAI tools expose a structured definition describing the operation. The tool definition contains information such as:

Tool name
Description
Parameters

For connection-backed tools, BindAI creates the definition explicitly. For example, a Webhook connection tool exposes a payload object parameter. A tool definition allows the runtime to understand the interface of the operation without executing it.

Tool Parameters

Tool parameters represent the inputs required by an operation. For example:

@tool
def increment(value: int) -> int:
    return value + 1

The operation expects a value input. Use clear parameter names and Python type annotations:

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

Clear parameter definitions make tools easier to use correctly from application and workflow code.

Tool Execution

A tool is executed with a BindAI execution context. The tool system provides the current variables and execution information through that context. Tool implementations can therefore access values supplied by the surrounding execution rather than requiring every value to be passed through a separate global mechanism. For example, a Tool implementation can read a variable from the execution context:

payload = context.variables.get("payload")

This is the mechanism used by connection-backed tools in V1.

Tool Results

Tool execution produces a ToolResult. A successful result can contain the operation’s output:

ToolResult(
    success=True,
    output=result,
    value=result,
)

A failed operation can return:

ToolResult(
    success=False,
    output=None,
    value=None,
    error="Operation failed.",
)

The result contains the execution status as well as the output or error information. The workflow runtime intentionally keeps this result object available in workflow variables. The Studio API converts these runtime objects into JSON-safe values at the HTTP boundary.

Tool Errors

Tools can fail during execution. A tool can report a failure through ToolResult:

return ToolResult(
    success=False,
    output=None,
    value=None,
    error="Database unavailable.",
)

Tool implementations should provide useful error messages without exposing secrets or unnecessary internal information. For example, avoid returning credentials, access tokens, or private connection configuration as part of an error.

ToolRegistry

BindAI provides a ToolRegistry for registering and resolving tools. The registry allows the runtime to look up a tool by name. This is important for workflow definitions because a persisted Tool node stores the tool name rather than serializing the Python callable itself. At runtime, the workflow loader resolves that name through the registry. Conceptually:

Workflow definition
        |
        v
    tool name
        |
        v
   ToolRegistry
        |
        v
   Tool instance
        |
        v
     Execute

This allows workflow definitions to remain serializable while the runtime uses the actual Python tool implementation.

Project Tool Discovery

BindAI Studio can discover tools from a project’s tool modules. For example:

my-project/
└── tools/
    ├── echo.py
    └── increment.py

The Studio runtime loads the project tools and registers them in the runtime ToolRegistry. The Studio API also exposes the project’s discovered tools. This allows the visual workflow editor to use project tools without embedding Python callable objects inside the workflow definition.

Tools in Workflows

Tools are directly supported by BindAI workflows. A workflow can contain a Tool node that executes a registered tool. For example:

Start
  |
  v
Agent
  |
  v
Tool
  |
  v
End

A Tool node identifies the registered tool and can map workflow variables to the tool’s parameters. For example, a workflow can map:

agent_output
     |
     v
Tool.text

The tool then receives the value when the node executes.

Tool Parameter Mapping

Workflow Tool nodes support parameter mapping. For example:

parameter_mapping:
  text: agent_output

This means:

workflow variable: agent_output
              |
              v
        tool parameter: text

Parameter mapping allows workflow nodes to pass values between agents, tools, and other workflow operations without requiring the tool itself to know about the workflow graph.

Agent and Tool Workflows

Tools can be combined with Agent nodes. For example:

Start
  |
  v
Agent
  |
  v
Tool
  |
  v
End

The Agent node can produce an output variable:

agent_output

The Tool node can then use that value through parameter mapping. A V1 example is:

- id: agent
  type: agent
  agent: classify_request
  input_variable: input
  output_variable: agent_output

- id: tool
  type: tool
  tool: echo
  output_variable: tool_output
  parameter_mapping:
    text: agent_output

This is a real V1 workflow pattern.

Connection-Backed Tools

BindAI V1 also supports tools backed by configured connections. The architecture is:

Connection
    |
    v
Connection-backed Tool
    |
    v
Workflow Tool node

The currently supported Studio connection provider is Webhook. A configured Webhook connection creates a corresponding tool such as:

webhook_<connection_name>

For example:

webhook_webh

The tool accepts a JSON payload and sends it through the configured Webhook connection. This allows a workflow to interact with an external HTTP endpoint without embedding the connection details directly in the workflow definition.

Webhook Tool Example

A Webhook connection-backed tool exposes a payload parameter:

payload

A workflow can map an existing variable to that parameter:

input
 |
 v
Webhook Tool
 |
 v
External Webhook

For example, the workflow input can contain:

{
  "source": "bindai-api",
  "message": "Connection workflow V1 test",
  "value": 42
}

The connection-backed tool sends that JSON payload to the configured Webhook URL. The connection credential is stored separately from the workflow definition.

Tools and Memory

Tools and Memory solve different problems. Memory provides stored execution or conversation context. Tools provide executable operations. They can therefore be used together in an agent or workflow:

Agent
  |
  +---- Memory
  |
  +---- Tool
  |
  v
Workflow

The exact behavior depends on how the agent and workflow are configured.

Tools and Knowledge

Tools can also be used alongside BindAI Knowledge. Knowledge provides access to configured project knowledge during agent execution. Tools provide executable operations. For example:

Agent
  |
  +---- Knowledge
  |
  +---- Tool
  |
  v
Response

This allows an application to combine retrieved project information with executable application capabilities.

Tools and Conditions

Tools can participate in workflow control flow. For example:

Start
  |
  v
Tool
  |
  v
Condition
  |
  +---- true ----> End
  |
  +---- false ---> End

The Tool node produces a workflow result that can then be used by subsequent workflow nodes. Conditions determine which workflow path executes.

Tools and Loops

A Tool node can also be part of a loop. For example:

Loop
  |
  v
Tool
  |
  v
Loop

This allows a workflow to repeatedly execute an operation while the workflow’s loop logic continues. The tool itself remains focused on its individual operation; the workflow controls the repetition.

Tools and Parallel Execution

Tools can participate in parallel workflow branches. For example:

             +--> Tool A --+
Start --> Parallel          --> Join
             +--> Tool B --+

The Parallel and Join nodes control workflow execution. Each Tool node remains an individual executable operation.

Tool Reuse

Project tools can be reused by multiple workflows. For example:

tools/
└── increment.py

The same registered tool can be referenced by different workflow definitions. This avoids duplicating the implementation of common operations. Tool reuse is especially useful for:

Common data transformations
API operations
Business logic
Project utilities
External integration operations

Tools and Studio

BindAI Studio exposes project tools to the visual workflow editor. The Studio API provides the project’s discovered tools so the editor can present available operations when configuring a Tool node. The workflow stores the tool name and configuration. At runtime, the project tool registry resolves the name to the actual tool implementation. This separates the visual workflow definition from the Python implementation.

Tool Security

Tools can execute real application logic and external operations. Applications should therefore treat tools as application boundaries. Important practices include:

Validate external input.
Do not expose credentials to the model.
Do not return secrets through tool results.
Keep destructive operations narrowly scoped.
Apply authorization in application code.
Validate important data before writing to external systems.
Avoid unnecessary side effects.

The language model should not be treated as an authorization boundary.

Testing Tools

Tools should be tested independently where possible. For example, a normal Python function can be tested directly:

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


assert multiply(2, 3) == 6

Workflow integration tests should additionally verify:

Tool registration
Tool discovery
Parameter mapping
Successful execution
Failed execution
Tool results
Agent-to-tool workflows
Connection-backed tools where applicable

BindAI’s V1 test suite includes tool and workflow coverage for these runtime behaviors.

Current V1 Tool Scope

The current BindAI V1 tool system includes:

Python project tools
The @tool decorator
Tool implementations
ToolDefinition
ToolResult
ToolRegistry
Project tool discovery
Workflow Tool nodes
Tool parameter mapping
Agent-to-Tool workflow execution
Connection-backed Webhook tools
Studio tool discovery

The following are not part of the verified V1 tool scope:

MCP tool management
A general marketplace of external tools
Provider-specific tool management UI
Automatic discovery of arbitrary external services

Summary

Tools provide BindAI with executable application capabilities. The basic project-tool pattern is:

from bindai_tool import tool


@tool
def echo(text: str) -> str:
    return text

The runtime can discover the project tool and register it with the ToolRegistry. Workflow definitions can then reference the tool by name:

type: tool
tool: echo

Workflow parameter mapping connects workflow variables to tool inputs:

parameter_mapping:
  text: input

Tools can also be backed by configured Webhook connections:

Connection
    |
    v
Connection-backed Tool
    |
    v
Workflow

Together, these mechanisms allow BindAI V1 applications to execute project-specific operations, connect workflow state to those operations, and integrate configured Webhook services without putting implementation details directly into workflow definitions.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

Connections

API Reference

Automation

Roadmap

03.1 overview

Tools Overview

What Is a Tool?

Creating Tools

Tool Definitions

Tool Parameters

Tool Execution

Tool Results

Tool Errors

ToolRegistry

Project Tool Discovery

Tools in Workflows

Tool Parameter Mapping

Agent and Tool Workflows

Connection-Backed Tools

Webhook Tool Example

Tools and Memory

Tools and Knowledge

Tools and Conditions

Tools and Loops

Tools and Parallel Execution

Tool Reuse

Tools and Studio

Tool Security

Testing Tools

Current V1 Tool Scope

Summary

​Tools Overview

​What Is a Tool?

​Creating Tools

​Tool Definitions

​Tool Parameters

​Tool Execution

​Tool Results

​Tool Errors

​ToolRegistry

​Project Tool Discovery

​Tools in Workflows

​Tool Parameter Mapping

​Agent and Tool Workflows

​Connection-Backed Tools

​Webhook Tool Example

​Tools and Memory

​Tools and Knowledge

​Tools and Conditions

​Tools and Loops

​Tools and Parallel Execution

​Tool Reuse

​Tools and Studio

​Tool Security

​Testing Tools

​Current V1 Tool Scope

​Summary

Tools Overview

What Is a Tool?

Creating Tools

Tool Definitions

Tool Parameters

Tool Execution

Tool Results

Tool Errors

ToolRegistry

Project Tool Discovery

Tools in Workflows

Tool Parameter Mapping

Agent and Tool Workflows

Connection-Backed Tools

Webhook Tool Example

Tools and Memory

Tools and Knowledge

Tools and Conditions

Tools and Loops

Tools and Parallel Execution

Tool Reuse

Tools and Studio

Tool Security

Testing Tools

Current V1 Tool Scope

Summary