Tools & Utilities

Overview

The swarms.tools module provides a comprehensive toolkit for function calling, schema conversion, and tool management. It enables seamless integration with OpenAI-style function calling, MCP (Model Context Protocol) tools, and Pydantic-based schema validation.

BaseTool

A comprehensive tool management system for function calling, schema conversion, and execution.

from swarms.tools import BaseTool

tool_manager = BaseTool(
    verbose=True,
    tools=[my_function],
    base_models=[MyModel]
)

Constructor

bool

default:"None"

Enable detailed logging output

List[type[BaseModel]]

default:"None"

List of Pydantic models to manage

bool

default:"None"

Enable automatic validation checks

bool

default:"None"

Enable automatic tool execution

List[Callable]

default:"None"

List of callable functions to manage

str

default:"None"

System prompt for tool operations

Dict[str, Callable]

default:"None"

Mapping of function names to callables

List[Dict[str, Any]]

default:"None"

List of dictionary representations of tool schemas

Methods

func_to_dict

Convert a callable function to OpenAI function calling schema dictionary.

schema = tool.func_to_dict(my_function)

Callable

required

The function to convert

Dict[str, Any]

OpenAI function calling schema dictionary

Raises:

FunctionSchemaError: If function schema conversion fails
ToolValidationError: If function validation fails

base_model_to_dict

Convert a Pydantic BaseModel to OpenAI function calling schema.

schema = tool.base_model_to_dict(MyModel, output_str=False)

type[BaseModel]

required

The Pydantic model class to convert

bool

default:"False"

Whether to return string output format

Union[dict[str, Any], str]

OpenAI function calling schema dictionary or JSON string

execute_tool

Execute a tool based on a response string.

result = tool.execute_tool('{"name": "my_function", "parameters": {...}}')

str

required

JSON response string containing tool execution details

Callable

Result of the tool execution

Raises:

ToolValidationError: If response validation fails
ToolExecutionError: If tool execution fails
ToolNotFoundError: If specified tool is not found

convert_funcs_into_tools

Convert all functions in the tools list into OpenAI function calling format.

tool.convert_funcs_into_tools()

This method processes all functions in the tools list, validates them for proper documentation and type hints, and converts them to OpenAI schemas. Raises:

ToolValidationError: If tools are not properly configured
ToolDocumentationError: If functions lack required documentation
ToolTypeHintError: If functions lack required type hints

execute_tool_by_name

Search for a tool by name and execute it with the provided response.

result = tool.execute_tool_by_name("add", '{"a": 1, "b": 2}')

str

required

The name of the tool to execute

str

required

JSON response string containing execution parameters

Any

The result of executing the tool

Tool Registry

swarms.tools exports a small registry pair: the ToolStorage class, which holds named tool callables, and the tool_registry decorator, which registers a function into a ToolStorage instance at import time.

from swarms.tools import ToolStorage, tool_registry

storage = ToolStorage(
    name="Math Tools",
    description="Arithmetic helpers for the agent",
)

@tool_registry(storage)
def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

# Look the tool back up by name and call it
add_fn = storage.get_tool("add")
print(add_fn(2, 3))  # 5

There is no tool decorator in swarms.tools. To hand a plain Python function to an agent, pass it directly via Agent(tools=[my_function]) — the framework generates the OpenAI schema from the function’s type hints and docstring. Use tool_registry only when you also want name-based lookup through a ToolStorage.

ToolStorage

str

default:"None"

Name of the registry

str

default:"None"

Description of the registry

bool

default:"None"

Enable detailed logging output

List[Callable]

default:"None"

Initial list of tool functions

Methods

Method	Description
`add_tool(func)`	Add a single tool. Raises `ValueError` if a tool with the same name already exists
`add_many_tools(funcs)`	Add a list of tools concurrently
`get_tool(name)`	Return the callable registered under `name`. Raises `ValueError` if not found
`list_tools()`	Return the registry contents as a formatted JSON string (name, documentation, creation time per tool)
`set_setting(key, value)`	Store an arbitrary setting on the registry
`get_setting(key)`	Read a setting back. Raises `KeyError` if not set

list_tools() returns a JSON string built from the registry’s metadata schema, not a list of tool names.

tool_registry

ToolStorage

default:"None"

The storage instance to register the decorated function in

Callable

A decorator that registers the function and returns a logging wrapper around it

Utility Functions

get_openai_function_schema_from_func

Convert a Python function to OpenAI function calling schema.

from swarms.tools import get_openai_function_schema_from_func

def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

schema = get_openai_function_schema_from_func(
    add,
    name="add_numbers",
    description="Add two integers"
)

base_model_to_openai_function

Convert a Pydantic BaseModel to OpenAI function schema.

from swarms.tools import base_model_to_openai_function
from pydantic import BaseModel

class UserInput(BaseModel):
    name: str
    age: int

schema = base_model_to_openai_function(UserInput)

scrape_tool_func_docs

Extract documentation from a tool function.

from swarms.tools import scrape_tool_func_docs

docs = scrape_tool_func_docs(my_function)

tool_find_by_name

Find a tool by name in a list of tools.

from swarms.tools import tool_find_by_name

tool = tool_find_by_name("calculator", tools_list)

MCP Tools Integration

MCP integration is handled by a single class, MCPManager. Point it at one or more servers and it manages transport, authentication, tool discovery, caching, and routing each call to the server that owns the tool.

from swarms.tools.mcp_manager import MCPManager

manager = MCPManager(mcp_url="http://localhost:8000/mcp")

manager.list_tool_names()                                  # discover
manager.get_tools()                                        # OpenAI schemas for an LLM
manager.call_tool("get_crypto_price", {"coin_id": "btc"})  # call one directly
manager.execute_tool_calls(llm_response)                   # run what a model asked for

MCPManager and MCPFileTokenStorage are exported from swarms.tools. See the MCPManager reference for the full API, and the MCP integration guide for using it from an agent.

Removed in favor of MCPManager. The standalone functions previously documented here — get_mcp_tools_sync, aget_mcp_tools, execute_tool_call_simple, get_tools_for_multiple_mcp_servers, and execute_multiple_tools_on_multiple_mcp_servers — no longer exist, along with the swarms.tools.mcp_client_tools module.

Removed	Replacement
`get_mcp_tools_sync(server_path=URL)`	`MCPManager(mcp_url=URL).get_tools()`
`aget_mcp_tools(server_path=URL)`	`await MCPManager(mcp_url=URL).aget_tools()`
`get_tools_for_multiple_mcp_servers(urls=URLS)`	`MCPManager(mcp_urls=URLS).get_tools()`
`execute_tool_call_simple(response=R, server_path=URL)`	`await MCPManager(mcp_url=URL).aexecute_tool_calls(R)`
`execute_multiple_tools_on_multiple_mcp_servers(...)`	`await MCPManager(mcp_urls=URLS).aexecute_tool_calls(R)`

Full migration notes, including the two behavioral differences, are in the MCPManager reference.

Additional Utilities

A few other symbols are exported from swarms.tools for less common use cases:

multi_base_model_to_openai_function — Convert several Pydantic BaseModel classes to a combined OpenAI function schema.
Function / ToolFunction — Pydantic models describing an OpenAI function and a tool wrapping one.
load_basemodels_if_needed / get_load_param_if_needed_function — Coerce raw dict arguments into the Pydantic models a tool’s signature declares.
get_parameters / get_required_params — Extract the JSON-schema parameter block and the list of required parameter names from a callable.
ToolStorage / tool_registry — Register and look up tools by name; see Tool Registry above.
MCPManager / MCPFileTokenStorage — MCP transport, auth, discovery, and routing; see the MCPManager reference.

Exceptions

BaseTool raises the exceptions below. They are defined in swarms.tools.base_tool and are not re-exported from swarms.tools, so import them from the module directly:

from swarms.tools.base_tool import (
    BaseToolError,
    ToolValidationError,
    ToolExecutionError,
    ToolNotFoundError,
    FunctionSchemaError,
    ToolDocumentationError,
    ToolTypeHintError,
)

All of them subclass BaseToolError.

BaseToolError

Base exception class for all BaseTool related errors.

ToolValidationError

Raised when tool validation fails.

ToolExecutionError

Raised when tool execution fails.

ToolNotFoundError

Raised when a requested tool is not found.

FunctionSchemaError

Raised when function schema conversion fails.

ToolDocumentationError

Raised when tool documentation is missing or invalid.

ToolTypeHintError

Raised when tool type hints are missing or invalid.

Best Practices

Always add type hints: Functions must have type hints for reliable schema generation
Include docstrings: Comprehensive docstrings improve tool descriptions
Validate inputs: Use Pydantic models for complex input validation
Handle errors: Wrap tool execution in try-catch blocks
Use caching: BaseTool caches expensive operations for performance
Enable verbose mode: During development, enable verbose logging to debug issues

Example: Complete Tool Setup

from swarms.tools import BaseTool
from pydantic import BaseModel

# Define a Pydantic model
class MathInput(BaseModel):
    a: int
    b: int
    operation: str

# Define a function with type hints and docstring
def calculate(a: int, b: int, operation: str) -> int:
    """Perform arithmetic operations on two numbers.
    
    Args:
        a: First number
        b: Second number
        operation: Operation to perform (add, subtract, multiply, divide)
    
    Returns:
        Result of the operation
    """
    if operation == "add":
        return a + b
    elif operation == "subtract":
        return a - b
    elif operation == "multiply":
        return a * b
    elif operation == "divide":
        return a // b
    else:
        raise ValueError(f"Unknown operation: {operation}")

# Create tool manager
tool_manager = BaseTool(
    verbose=True,
    tools=[calculate],
    base_models=[MathInput]
)

# Convert tools to OpenAI schema
tool_manager.convert_funcs_into_tools()

# Execute a tool
result = tool_manager.execute_tool_by_name(
    "calculate",
    '{"a": 10, "b": 5, "operation": "multiply"}'
)
print(result)  # 50

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

Tools & Utilities

Overview

BaseTool

Constructor

Methods

func_to_dict

base_model_to_dict

execute_tool

convert_funcs_into_tools

execute_tool_by_name

Tool Registry

ToolStorage

Methods

tool_registry

Utility Functions

get_openai_function_schema_from_func

base_model_to_openai_function

scrape_tool_func_docs

tool_find_by_name

MCP Tools Integration

Additional Utilities

Exceptions

BaseToolError

ToolValidationError

ToolExecutionError

ToolNotFoundError

FunctionSchemaError

ToolDocumentationError

ToolTypeHintError

Best Practices

Example: Complete Tool Setup

​Overview

​BaseTool

​Constructor

​Methods

​func_to_dict

​base_model_to_dict

​execute_tool

​convert_funcs_into_tools

​execute_tool_by_name

​Tool Registry

​ToolStorage

​Methods

​tool_registry

​Utility Functions

​get_openai_function_schema_from_func

​base_model_to_openai_function

​scrape_tool_func_docs

​tool_find_by_name

​MCP Tools Integration

​Additional Utilities

​Exceptions

​BaseToolError

​ToolValidationError

​ToolExecutionError

​ToolNotFoundError

​FunctionSchemaError

​ToolDocumentationError

​ToolTypeHintError

​Best Practices

​Example: Complete Tool Setup

Overview

BaseTool

Constructor

Methods

func_to_dict

base_model_to_dict

execute_tool

convert_funcs_into_tools

execute_tool_by_name

Tool Registry

ToolStorage

Methods

tool_registry

Utility Functions

get_openai_function_schema_from_func

base_model_to_openai_function

scrape_tool_func_docs

tool_find_by_name

MCP Tools Integration

Additional Utilities

Exceptions

BaseToolError

ToolValidationError

ToolExecutionError

ToolNotFoundError

FunctionSchemaError

ToolDocumentationError

ToolTypeHintError

Best Practices

Example: Complete Tool Setup