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 Decorator

A decorator function that generates an OpenAI function schema from a Python function.

from swarms.tools import tool

@tool(name="calculator", description="Perform arithmetic operations")
def calculate(a: int, b: int, operation: str) -> int:
    """Calculate result of operation on two numbers."""
    if operation == "add":
        return a + b
    elif operation == "multiply":
        return a * b

str

default:"None"

The name of the OpenAI function

str

default:"None"

The description of the OpenAI function

bool

default:"True"

Whether to return the schema as a dictionary

bool

default:"True"

Enable verbose logging

bool

default:"False"

Whether to return the schema as a string

bool

default:"False"

Whether to return the schema as YAML

Note: name and description are declared with a default of None, but the decorator asserts both are strings at call time — omitting either raises AssertionError. Also, calling the decorated function executes the original function body but returns its generated schema (not the function’s return value).

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 utilities are exported from swarms.tools for less common use cases:

base_model_to_json — Convert a Pydantic BaseModel class to a formatted JSON schema string.
ToolStorage / tool_registry — Register and look up tools by name in a shared, process-wide tool registry.
create_computer_use_tools — Create a dict of pre-configured computer-use tools (file read/write, shell execution) scoped to a workspace directory. from swarms.tools import create_computer_use_tools.
execute_multiple_tools_on_multiple_mcp_servers / execute_multiple_tools_on_multiple_mcp_servers_sync — Execute several tool calls across several MCP servers concurrently (async and sync variants).

Exceptions

The tools module defines several custom exceptions:

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, tool
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 Decorator

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 Decorator

​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 Decorator

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