Shared Tools

Shared Tools are reusable tool implementations that can be used by multiple agents, workflows, or applications. Instead of duplicating the same functionality across different parts of an AI system, a shared tool can be implemented once and reused wherever it is appropriate. This improves consistency, maintainability, testing, and code reuse.

What Are Shared Tools?

A shared tool is a reusable tool implementation that is intentionally made available to multiple consumers. Conceptually:

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

The tool itself remains a normal BindAI tool. “Shared” describes how the application organizes and reuses that tool; it does not necessarily imply a special SharedTool class.

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 operation to all three consumers:

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

Benefits include:

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

BindAI Tool Registry

BindAI provides a tool registry for registering and resolving tools. Conceptually:

ToolRegistry
    |
    +---- Search
    +---- Database
    +---- Email
    +---- Calendar
    +---- Retrieval

Agents can be configured with tools through the agent builder. For example:

agent = Agent.builder().tool(search_tool).tool(database_tool).build()

The same tool implementation can be supplied to multiple agents when appropriate.

A reusable tool can be configured for more than one agent. Conceptually:

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

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

Both agents use the same tool implementation. This does not require the tool itself to know which agent is using it.

Shared Tools and Workflows

Tools can also be reused by workflow operations. For example:

Workflow
    |
    +---- Agent
    |
    +---- Search Tool
    |
    +---- Database Tool
    |
    +---- Notification Tool

A workflow can therefore reuse the same tool implementations used by agents elsewhere in the application. The exact workflow integration depends on the current workflow API.

Shared Tools and Applications

Applications can organize common tools for use across multiple application boundaries. Conceptually:

Project

├── Support Application
│      └── Search Tool
│
├── Sales Application
│      └── Search Tool
│
└── Research Application
       └── Search Tool

The applications can reference the same implementation where appropriate. The project itself does not need to provide a special global tool object for this pattern.

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
Stable interface is valuable	Can evolve with its consumer
Useful across applications	Useful for one workflow or agent

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

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 the agent or workflow. Connection Handles communication with an external service. This separation makes integrations easier to reuse.

Shared Tools and Knowledge

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

Agent
   |
   v
Knowledge Tool
   |
   v
Knowledge / Retriever

However, agents can also integrate Knowledge directly through BindAI’s Knowledge and retrieval capabilities. A dedicated tool is therefore useful only when the application benefits from explicit tool-based access.

Shared Tools and Memory

Tools can interact with memory when an application explicitly provides the required memory capability. For example:

Agent
   |
   v
Tool
   |
   v
Memory Provider

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

Tool Interfaces

Shared tools should have stable, understandable interfaces. A typical tool should define:

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 agents without changing the interface.

Avoiding Hidden Dependencies

Shared tools should avoid depending on 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

Sharing a tool does not mean every consumer should automatically have unrestricted access to everything the tool can do.

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 all 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, the tool can return a structured failure through BindAI’s tool execution 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 rather than a required BindAI directory structure. The important goal is to keep related capabilities easy to discover.

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 controls to implement cross-cutting concerns such as logging, tracing, authorization, or request policies where supported.

Shared Tools and Workflows

A shared tool can participate in larger workflows:

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

This allows the same business operation to be reused in both direct agent execution and orchestrated workflows.

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

BindAI provides the underlying tool abstractions required for reusable tools. The current tool system includes:

Tool definitions
Tool registration
Tool registries
Tool execution
Tool results
Agent tool integration
Multiple tools per agent

The project-level concept of a Shared Tool is an organizational pattern built on these capabilities. BindAI should not currently be assumed to provide a dedicated project-wide SharedTool runtime abstraction.

API Accuracy

This document intentionally avoids assuming a project-level API such as:

project.add_tool(...)
project.tools(...)
project.tool(...)
shared_tool(...)

unless those methods are verified in the current implementation. The verified pattern is to define reusable tools and register or attach them to the agents or execution components that need them. For example:

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

The same search_tool object or implementation can be reused by another agent.

Summary

Shared Tools are reusable tool implementations that can serve multiple agents, workflows, or applications. The basic pattern is:

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

BindAI’s existing tool registry and agent tool configuration provide the foundation for this pattern. A project does not need a special global tool abstraction to benefit from shared tools. Reusable implementations, explicit interfaces, controlled permissions, and careful testing provide the core of effective tool sharing.

​Shared Tools

​What Are Shared Tools?

​Why Use Shared Tools?

​BindAI Tool Registry

​Sharing a Tool Between Agents

​Shared Tools and Workflows

​Shared Tools and Applications

​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

​Shared Tools and Workflows

​When Not to Share a Tool

​Best Practices

​Current BindAI Scope

​API Accuracy

​Summary

Shared Tools

What Are Shared Tools?

Why Use Shared Tools?

BindAI Tool Registry

Sharing a Tool Between Agents

Shared Tools and Workflows

Shared Tools and Applications

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

Shared Tools and Workflows

When Not to Share a Tool

Best Practices

Current BindAI Scope

API Accuracy

Summary