Shared Tools

Shared tools are reusable tool implementations that can be made available to multiple agents, workflows, or applications within a BindAI project. BindAI does not require a special SharedTool class. Instead, sharing is achieved by reusing normal BindAI tool implementations and, at the project level, registering them through the project’s tool registry. This provides a simple foundation for reusing business capabilities without duplicating tool implementations.

What Are Shared Tools?

A shared tool is a normal BindAI tool that is intentionally reused by multiple consumers. Conceptually:

Project
   |
   +---- Shared Tool
           |
           +---- Agent A
           +---- Agent B
           +---- Workflow
           +---- Application

The tool itself does not need to know that it is shared. “Shared” describes how the tool is organized and reused by the project.

Why Use Shared Tools?

Without reusable tools, applications may duplicate the same functionality. For example:

Support Agent
   |
   +---- Database Lookup

Sales Agent
   |
   +---- Database Lookup

HR Agent
   |
   +---- Database Lookup

A shared implementation can instead provide the same capability to multiple consumers:

             Database Lookup
              /      |      \
             /       |       \
    Support Agent  Sales Agent  HR Agent

Benefits include:

Less code duplication
Consistent behavior
Centralized maintenance
Easier testing
Reusable business logic
Simpler upgrades

Project Tool Registry

A BindAI Project owns a tool registry:

project.tools

Tools can be added to the project with:

project.add_tool(search_tool)

The project implementation delegates registration to its internal tool registry. Conceptually:

Project
   |
   +---- Tool Registry
           |
           +---- Search
           +---- Database
           +---- Email
           +---- Retrieval

The project-level registry is useful when tools represent capabilities that should be available across the project rather than belonging exclusively to one application.

Adding a Shared Tool to a Project

A reusable tool can be registered with a project:

project.add_tool(search_tool)

Project.add_tool() returns the project, allowing chained project construction:

project = (
    Project(configuration)
    .add_tool(search_tool)
)

The project therefore provides a concrete place for project-wide tool registration.

A tool implementation can also be supplied directly to multiple agents. For example:

support_agent = (
    Agent.builder()
    .tool(search_tool)
    .build()
)

research_agent = (
    Agent.builder()
    .tool(search_tool)
    .build()
)

Both agents can use the same tool implementation. The tool does not need to know which agent is invoking it. The exact way an agent receives tools depends on the current agent builder and tool APIs.

Shared Tools and Applications

A project can contain multiple applications:

Project
├── Support Application
├── Sales Application
└── Research Application

A reusable tool can support capabilities used across those application boundaries. For example:

Project
   |
   +---- Search Tool
           |
           +---- Support
           +---- Sales
           +---- Research

The important distinction is between the project-level organization of the tool and the way individual agents consume it. Applications do not need a separate SharedTool abstraction.

Shared Tools and Workflows

Tools can participate in workflow execution as well as agent execution. Conceptually:

Workflow
   |
   +---- Agent
   |
   +---- Tool
   |
   +---- Condition
   |
   +---- Human Task

A reusable business capability can therefore be implemented once and used from multiple execution paths. The exact workflow integration depends on the workflow and tool APIs used by the application.

Shared Tools vs Local Tools

Not every tool needs to be shared.

Shared Tool	Local Tool
Used by multiple consumers	Used by one consumer
Reusable implementation	Task-specific implementation
Maintained centrally	Maintained locally
Useful across applications	Useful for one agent or workflow
Stable interface is valuable	Can evolve with its consumer

If a tool is only used once, keeping it close to the agent or workflow that owns it may be simpler.

Typical Shared Tools

Common candidates for reuse include:

Database queries
Search
Document retrieval
Email delivery
Calendar operations
File storage
CRM operations
Internal APIs
Notification services
Data transformation
Analytics utilities

Tools that represent stable business capabilities are particularly good candidates for sharing.

Shared Tools and Connections

A shared tool can use a BindAI Connection to communicate with an external service. For example:

Agent
   |
   v
Shared Tool
   |
   v
Connection
   |
   v
External Service

This separates two concerns. Tool Defines the operation available to an agent or workflow. Connection Handles communication with an external service. This separation makes external integrations easier to reuse. For example, a reusable customer lookup tool could use a CRM connection internally while presenting a stable tool interface to agents. Connections are provided by the separate bindai-connections package.

Shared Tools and Knowledge

Knowledge retrieval can be exposed through reusable tools when an application benefits from tool-based access. For example:

Agent
   |
   v
Knowledge Tool
   |
   v
Knowledge / Retriever

However, BindAI also provides direct knowledge and retrieval capabilities. A dedicated tool is therefore useful when the application specifically wants knowledge retrieval to appear as a tool operation.

Shared Tools and Memory

A shared tool can interact with memory when the application explicitly provides the required memory capability. For example:

Agent
   |
   v
Tool
   |
   v
Memory Provider

Memory should not automatically be treated as global. If a shared tool accesses memory, the application should define the appropriate scope and permissions.

Tool Interfaces

Shared tools should have stable and understandable interfaces. A reusable tool should generally provide:

A clear name
Explicit parameters
Useful type hints
A focused responsibility
A descriptive docstring
Predictable results
Safe error handling

For example:

def search_customer(customer_id: str) -> dict:
    """Return information for a customer."""
    ...

The implementation can then be reused by multiple consumers without changing the interface.

Avoiding Hidden Dependencies

Shared tools should avoid unnecessary hidden global state. Prefer explicit inputs:

def get_customer(customer_id: str) -> dict:
    ...

over implicit application state:

def get_current_customer() -> dict:
    ...

Explicit dependencies make shared tools easier to test and reuse.

Configuration

Shared tools may require configuration such as:

API endpoints
Database connections
Service identifiers
Feature settings
Environment-specific behavior

Configuration should remain separate from the tool implementation where possible. Secrets should not be hard-coded. Use environment variables or an appropriate secret-management system for sensitive credentials.

Security

Shared tools can expose powerful capabilities. Examples include:

Database writes
Customer data access
File operations
Payment operations
External API calls
Administrative actions

A shared tool should therefore enforce appropriate safety boundaries. Consider:

Input validation
Authorization
Least privilege
Sensitive-data handling
Safe error messages
Audit logging
Rate limiting
Idempotency for important operations

Registering a tool at the project level does not by itself establish authorization rules for every consumer. Applications should still enforce the appropriate security boundaries for sensitive operations.

Read vs Write Tools

A useful distinction is between read-only and state-changing operations.

Read

Agent
   |
   v
Search Tool
   |
   v
Read Data

Write

Agent
   |
   v
Update Tool
   |
   v
Change External State

Write operations generally require stronger validation and authorization. This distinction becomes especially important when the same tool is used by multiple agents.

Idempotency

Shared tools that perform external side effects should consider idempotency. For example:

Agent
   |
   v
Shared Tool
   |
   v
Create External Resource

If the operation is retried, the system should avoid unintentionally creating duplicate resources when possible. Useful techniques include:

Idempotency keys
Duplicate detection
Stable operation identifiers
Transactional behavior

Versioning

A shared tool may have many consumers. For example:

Shared Tool v1
   |
   +---- Agent A
   +---- Agent B
   +---- Agent C

Changing its interface can therefore affect several consumers. When evolving shared tools:

Preserve compatibility when possible.
Test important consumers.
Document interface changes.
Avoid unnecessary breaking changes.
Introduce new interfaces deliberately.

Stable interfaces reduce maintenance costs.

Performance

Frequently used shared tools should be designed with performance in mind. Consider:

Caching
Connection pooling
Batching
Async execution where appropriate
Reducing unnecessary network calls
Avoiding repeated expensive computation

A performance improvement to a shared tool can benefit every consumer.

Error Handling

Shared tools should return predictable results and handle failures safely. Potential failures include:

Invalid input
Network errors
Authentication failures
External service errors
Database errors
Rate limits
Timeouts

Tool failures should not expose secrets or unnecessary internal implementation details. Where appropriate, failures should be represented through BindAI’s tool execution and result model.

Testing Shared Tools

Shared tools should be tested independently of the agents that consume them. Recommended tests include:

Valid inputs
Invalid inputs
Boundary cases
External-service failures
Authentication failures
Timeouts
Duplicate requests
Side effects
Security restrictions

For example:

Shared Tool
    |
    +---- Unit Tests
    +---- Failure Tests
    +---- Security Tests
    +---- Integration Tests

Consumer agents can then have separate tests verifying that they invoke the tool correctly.

Reuse Across Agents

A shared tool should remain independent of a particular agent. Good:

Search Tool
    |
    +---- Support Agent
    +---- Research Agent
    +---- Sales Agent

Avoid implementations that contain assumptions such as:

Search Tool
    |
    +---- Only works for Support Agent

Reusable tools should depend on explicit inputs and configuration rather than the identity of their consumer.

Organizing Shared Tools

As a project grows, tools can be organized into logical modules. For example:

tools/
├── communication/
├── database/
├── retrieval/
├── integrations/
├── utilities/
└── analytics/

This is an organizational convention, not a required BindAI directory structure. The important goal is to keep related capabilities easy to discover and maintain.

Shared Tools and Middleware

Shared tools can be used alongside agent middleware and other execution controls. For example:

Agent
   |
   v
Middleware
   |
   v
Tool Execution
   |
   v
External Service

Applications can use middleware or other supported execution controls for cross-cutting concerns such as logging, tracing, authorization, or request policies. The exact middleware behavior depends on the execution path being used.

Sharing is not always the right choice. Keep a tool local when:

It is highly specific to one agent.
Its interface changes frequently.
Its behavior depends heavily on local state.
Its permissions are unique to one application.
Reuse would introduce unnecessary coupling.

A smaller local abstraction is often preferable to premature centralization.

Best Practices

Share tools that represent genuinely reusable capabilities.
Keep each tool focused on one responsibility.
Use explicit parameters and type hints.
Keep shared interfaces stable.
Avoid hidden global state.
Separate configuration from implementation.
Protect sensitive operations.
Prefer least-privilege access.
Make external side effects idempotent where possible.
Test shared tools independently.
Document breaking changes.
Keep tool organization modular.

Current BindAI Scope

The current BindAI project model provides a concrete project-level tool registry. A Project initializes:

self.tools = ToolRegistry()

and exposes:

project.add_tool(tool)

The project therefore has a real mechanism for registering tools at project scope. The current project API also includes:

project.add_application(application)
project.add_workflow(workflow)
project.add_schedule(schedule)

This makes project-level tool registration part of the broader project composition model. The project does not currently expose a separate SharedTool class. Instead, shared tools are normal BindAI tools that are registered or attached wherever they are needed.

Project-Level Tool Registration

A typical project can register a reusable tool like this:

project = Project(configuration)

project.add_tool(search_tool)

The same tool implementation can then be reused by consumers that are configured to use it. The exact mechanics of attaching project-registered tools to individual agents or workflow operations depend on the relevant agent and workflow APIs. The important distinction is:

Project
   |
   +---- Project Tool Registry
            |
            +---- Reusable Tool

versus a special runtime type such as:

SharedTool

BindAI does not currently require the latter.

API Accuracy

The verified project-level APIs are:

project.tools

and:

project.add_tool(tool)

Project.add_tool() registers the supplied tool with the project’s tool registry and returns the project instance. The project also provides:

project.add_application(application)
project.application(name)

project.add_workflow(workflow)
project.workflow(workflow_id)

project.run(
    application="support",
    agent="support_agent",
    message="Hello",
)

project.stream(
    application="support",
    agent="support_agent",
    message="Hello",
)

The current documentation should not assume additional project-level methods such as:

project.tool(...)
project.shared_tool(...)
project.register_shared_tool(...)

unless they are added to the implementation.

Summary

Shared tools are reusable BindAI tool implementations that can serve multiple agents, workflows, or applications. The project model provides a concrete project-level tool registry:

Project
   |
   +---- Tool Registry
           |
           +---- Search Tool
           +---- Database Tool
           +---- Notification Tool

Tools can also be attached directly to agents where appropriate. The key pattern is:

Reusable Tool
      |
      +---- Agent A
      +---- Agent B
      +---- Workflow
      └---- Application

BindAI does not need a special SharedTool runtime abstraction to support this pattern. Project-level registration, reusable tool implementations, explicit interfaces, controlled permissions, and independent testing provide the foundation for effective tool sharing.

​Shared Tools

​What Are Shared Tools?

​Why Use Shared Tools?

​Project Tool Registry

​Adding a Shared Tool to a Project

​Sharing a Tool Between Agents

​Shared Tools and Applications

​Shared Tools and Workflows

​Shared Tools vs Local Tools

​Typical Shared Tools

​Shared Tools and Connections

​Shared Tools and Knowledge

​Shared Tools and Memory

​Tool Interfaces

​Avoiding Hidden Dependencies

​Configuration

​Security

​Read vs Write Tools

​Read

​Write

​Idempotency

​Versioning

​Performance

​Error Handling

​Testing Shared Tools

​Reuse Across Agents

​Organizing Shared Tools

​Shared Tools and Middleware

​When Not to Share a Tool

​Best Practices

​Current BindAI Scope

​Project-Level Tool Registration

​API Accuracy

​Summary