Agent Tools - swarms

Tools extend agent capabilities by allowing them to call external functions, APIs, and services. Swarms supports OpenAI-style function calling with automatic schema generation. Each agent runs its tools through a ToolManager, available as agent.tool_manager. It builds the schemas, executes each call, retries failures, and prints tool activity.

Basic Tool Usage

Define a Simple Tool

Tools are Python functions with type hints and docstrings:

from swarms import Agent

def get_weather(location: str, units: str = "celsius") -> str:
    """
    Get the current weather for a location.
    
    Args:
        location: The city and country, e.g., 'San Francisco, CA'
        units: Temperature units ('celsius' or 'fahrenheit')
    
    Returns:
        Weather information as a string
    """
    # Your weather API logic here
    return f"Weather in {location}: 72°{units[0].upper()}, sunny"

# Create agent with tool
agent = Agent(
    agent_name="Weather-Assistant",
    model_name="claude-sonnet-4-6",
    max_loops=1,
    tools=[get_weather],  # Add tools as a list
)

# Agent can now call the tool
response = agent.run("What's the weather in New York?")
print(response)

Tool Requirements

Type Hints and Docstrings

For reliable tool execution, functions must have:

Type hints for every parameter without a default. A missing one raises TypeError when the agent is built. A missing return annotation only logs a warning.
A docstring describing the function’s purpose. A missing one raises ValueError when the agent is built.
Parameter descriptions the model can read. The whole docstring, Args: section included, becomes the tool description.

# Good - Complete type hints and docstring
def search_web(query: str, max_results: int = 10) -> str:
    """
    Search the web and return results.
    
    Args:
        query: The search query string
        max_results: Maximum number of results to return
    
    Returns:
        Search results as formatted text
    """
    # Implementation
    return f"Results for: {query}"

# Bad - Missing type hints
def search_web(query, max_results=10):  # ❌ No type hints
    return f"Results for: {query}"

# Bad - Missing docstring  
def search_web(query: str) -> str:  # ❌ No docstring
    return f"Results for: {query}"

How the schema is built

The agent converts each callable to an OpenAI function schema when it is constructed:

Schema field	Comes from
`name`	The function’s `__name__`
`description`	The full docstring, verbatim
Parameter types	The type annotations
Parameter descriptions	`Annotated[type, "description"]` metadata, or else the parameter name
`required`	Every parameter without a default

To give a single parameter its own description in the schema, use Annotated:

from typing import Annotated

def get_weather(
    location: Annotated[str, "City and country, e.g. 'Paris, France'"],
    units: Annotated[str, "'celsius' or 'fahrenheit'"] = "celsius",
) -> str:
    """Get the current weather for a location."""
    return f"Weather in {location}: 22 {units}"

Multiple Tools

Add Multiple Tools to an Agent

def calculate(expression: str) -> float:
    """
    Calculate a mathematical expression.
    
    Args:
        expression: A mathematical expression like '2 + 2'
    
    Returns:
        The result of the calculation
    """
    return eval(expression)  # Use a safe evaluator in production

def get_time(timezone: str = "UTC") -> str:
    """
    Get the current time in a timezone.
    
    Args:
        timezone: The timezone name (e.g., 'UTC', 'America/New_York')
    
    Returns:
        Current time as a string
    """
    from datetime import datetime
    import pytz
    
    tz = pytz.timezone(timezone)
    return datetime.now(tz).strftime("%Y-%m-%d %H:%M:%S %Z")

def search_database(query: str) -> str:
    """
    Search the internal database.
    
    Args:
        query: SQL query to execute
    
    Returns:
        Query results
    """
    # Database logic here
    return "Query results..."

# Agent with multiple tools
agent = Agent(
    agent_name="Multi-Tool-Agent",
    model_name="claude-sonnet-4-6",
    max_loops=2,
    tools=[calculate, get_time, search_database],
    verbose=True,
)

response = agent.run(
    "What time is it in Tokyo and what's 123 * 456?"
)

Real-World Tool Examples

Web Search Tool

import requests

def web_search(query: str, num_results: int = 5) -> str:
    """
    Search the web using a search API.
    
    Args:
        query: The search query
        num_results: Number of results to return (1-10)
    
    Returns:
        Formatted search results
    """
    # Example using a hypothetical search API
    response = requests.get(
        "https://api.searchengine.com/search",
        params={"q": query, "limit": num_results}
    )
    results = response.json().get("results", [])
    
    formatted = []
    for i, result in enumerate(results, 1):
        formatted.append(
            f"{i}. {result['title']}\n   {result['snippet']}\n   {result['url']}"
        )
    
    return "\n\n".join(formatted)

agent = Agent(
    agent_name="Research-Agent",
    model_name="claude-sonnet-4-6",
    tools=[web_search],
)

Database Query Tool

import sqlite3
from typing import List, Dict, Any

def query_database(sql: str) -> List[Dict[str, Any]]:
    """
    Execute a SQL query on the database.
    
    Args:
        sql: SQL query to execute (SELECT statements only)
    
    Returns:
        Query results as a list of dictionaries
    """
    # Validate it's a SELECT query
    if not sql.strip().upper().startswith("SELECT"):
        return [{"error": "Only SELECT queries are allowed"}]
    
    conn = sqlite3.connect("data.db")
    cursor = conn.cursor()
    
    try:
        cursor.execute(sql)
        columns = [desc[0] for desc in cursor.description]
        results = [
            dict(zip(columns, row))
            for row in cursor.fetchall()
        ]
        return results
    except Exception as e:
        return [{"error": str(e)}]
    finally:
        conn.close()

agent = Agent(
    agent_name="Data-Analyst",
    model_name="claude-sonnet-4-6",
    tools=[query_database],
)

File Operations Tool

import os
from pathlib import Path

def read_file(filepath: str) -> str:
    """
    Read the contents of a file.
    
    Args:
        filepath: Path to the file to read
    
    Returns:
        File contents as a string
    """
    try:
        with open(filepath, "r") as f:
            return f.read()
    except Exception as e:
        return f"Error reading file: {e}"

def write_file(filepath: str, content: str) -> str:
    """
    Write content to a file.
    
    Args:
        filepath: Path to the file to write
        content: Content to write to the file
    
    Returns:
        Success or error message
    """
    try:
        Path(filepath).parent.mkdir(parents=True, exist_ok=True)
        with open(filepath, "w") as f:
            f.write(content)
        return f"Successfully wrote to {filepath}"
    except Exception as e:
        return f"Error writing file: {e}"

def list_directory(path: str = ".") -> str:
    """
    List files and directories in a path.
    
    Args:
        path: Directory path to list (default: current directory)
    
    Returns:
        List of files and directories
    """
    try:
        items = os.listdir(path)
        return "\n".join(items)
    except Exception as e:
        return f"Error listing directory: {e}"

agent = Agent(
    agent_name="File-Manager",
    model_name="claude-sonnet-4-6",
    tools=[read_file, write_file, list_directory],
    max_loops=3,
)

Tool Configuration

Tool Schema Control

List[Callable]

default:"None"

List of tool functions to make available to the agent.

agent = Agent(
    tools=[tool1, tool2, tool3],
    model_name="claude-sonnet-4-6"
)

tool_choice is not an Agent constructor parameter. Whenever tools (or MCP tools) are configured, the agent always sends tool_choice="auto" to the underlying LLM call — passing tool_choice=... to Agent(...) is silently absorbed into **kwargs and has no effect.

bool

default:"False"

Defer tool schemas behind a searchable tool_search tool instead of sending every schema on every request. Off by default. When on, deferral activates if the agent has tools, an MCP connection, or max_loops="auto".

agent = Agent(
    tools=[tool1, tool2, tool3],
    dynamic_tools=True,  # send only tool_search up front
)

See Dynamic Tool Loading for how deferral, search ranking, and turn budgeting work.

With deferral active, a tool costs one extra round trip: the model must call tool_search before it can call the tool. With max_loops=1 it can search but never call what it found. Raise max_loops or leave dynamic_tools off.

bool

default:"True"

When True, print a Tool Execution Results panel with the time, each tool’s name and call id, and the full output. When False, print a short panel with just the tool names and the time. Nothing is printed when print_on=False.

agent = Agent(
    tools=[my_tool],
    show_tool_execution_output=False,
)

int

default:"3"

How many times the batch of tool calls from one reply runs before the agent gives up. Each attempt runs the whole batch once, so calls that succeeded run again with it.

agent = Agent(
    tools=[my_tool],
    tool_retry_attempts=5,
)

bool

default:"True"

After each tool batch, make one extra model call to summarize the output and add the summary to the conversation. Set to False to skip the extra call. A plain-text reply that calls no tool is never summarized.

When every attempt fails, the agent does not retry the model call. It records Tool execution failed after N attempts: ... in the conversation and moves to the next loop, so the model can read the error and try something else. Provider retries (retry_attempts) are not used up by a broken tool. See ToolManager for the details.

Adding tools after construction

add_tool, add_tools, remove_tool, and remove_tools change only agent.tools. The schemas, the executor, and the LLM are built once, at construction, so pass every tool to the constructor when you can. To rebuild after a change, see ToolManager.

Advanced Tool Patterns

Tool with State

class DatabaseTool:
    def __init__(self, db_path: str):
        self.db_path = db_path
        self.connection = None
    
    def connect(self) -> str:
        """
        Connect to the database.
        
        Returns:
            Connection status message
        """
        import sqlite3
        self.connection = sqlite3.connect(self.db_path)
        return "Connected to database"
    
    def query(self, sql: str) -> str:
        """
        Execute a SQL query.
        
        Args:
            sql: SQL query to execute
        
        Returns:
            Query results
        """
        if not self.connection:
            return "Not connected to database"
        
        cursor = self.connection.cursor()
        cursor.execute(sql)
        results = cursor.fetchall()
        return str(results)

# Create instance and use methods as tools
db_tool = DatabaseTool("data.db")

agent = Agent(
    agent_name="DB-Agent",
    model_name="claude-sonnet-4-6",
    tools=[db_tool.connect, db_tool.query],
)

Async Tools

import asyncio
import aiohttp

async def fetch_url_async(url: str) -> str:
    """
    Fetch content from a URL asynchronously.
    
    Args:
        url: The URL to fetch
    
    Returns:
        Response content
    """
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.text()

# Wrap async function for synchronous agent
def fetch_url(url: str) -> str:
    """
    Fetch content from a URL.
    
    Args:
        url: The URL to fetch
    
    Returns:
        Response content
    """
    return asyncio.run(fetch_url_async(url))

agent = Agent(
    model_name="claude-sonnet-4-6",
    tools=[fetch_url],
)

BaseTool API

Swarms uses the BaseTool class internally to convert and run tools. Every agent keeps one as agent.tool_struct, and its ToolManager calls it for each batch of local tool calls. You can also use it on its own:

from swarms.tools.base_tool import BaseTool

# Tools are automatically converted to OpenAI function schemas
base_tool = BaseTool(
    tools=[my_function],
    verbose=True,
)

# Get function schema
schema = base_tool.convert_tool_into_openai_schema()
print(schema)

# Execute a tool
result = base_tool.execute_tool(
    response='{"name": "my_function", "parameters": {...}}'
)

MCP Tools

Model Context Protocol (MCP) enables connecting to external tool servers:

from swarms.schemas.mcp_schemas import MCPConnection
from swarms import Agent

# streamable_http is the default transport; stdio servers take command and args instead
mcp_config = MCPConnection(
    url="http://localhost:8000/mcp",
    transport="streamable_http",
)

agent = Agent(
    agent_name="MCP-Agent",
    model_name="claude-sonnet-4-6",
    mcp_config=mcp_config,  # Tools auto-loaded from MCP server
)

# Agent can now use all tools from the MCP server
response = agent.run("What's the weather in Paris?")

Simpler alternative for a single server — pass the URL directly with mcp_url:

agent = Agent(
    agent_name="MCP-Agent",
    model_name="claude-sonnet-4-6",
    mcp_url="http://localhost:8000/mcp",
)

In an agent with an integer max_loops, keep MCP servers and local tools on separate agents. When tools is set, every tool call in a reply goes to the local executor first, and an MCP tool name makes that batch fail. With max_loops="auto", MCP calls are routed to the MCP manager separately. See ToolManager.

Sub-agents in autonomous mode

With max_loops="auto", an agent can create sub-agents with the create_sub_agent tool. Each sub-agent gets the parent’s model_name, its tools list, and its print_on and verbose settings. A sub-agent with tools runs up to 5 loops, so it can call a tool and read the result. A sub-agent without tools runs 1 loop. MCP servers and handoffs are not passed down. See Autonomous mode.

Best Practices

1. Always Include Type Hints

# Good
def search(query: str, limit: int = 10) -> list[dict]:
    """Search with proper types"""
    pass

# Bad
def search(query, limit=10):  # ❌ No type hints
    pass

2. Write Descriptive Docstrings

# Good
def analyze_data(data: str, method: str = "statistical") -> dict:
    """
    Analyze data using specified method.
    
    Args:
        data: JSON string containing data to analyze
        method: Analysis method ('statistical', 'ml', 'deep_learning')
    
    Returns:
        Dictionary with analysis results including metrics and insights
    """
    pass

# Bad
def analyze_data(data: str) -> dict:
    """Analyze data"""  # ❌ Not descriptive enough
    pass

3. Handle Errors Gracefully

def api_call(endpoint: str) -> str:
    """
    Make an API call.
    
    Args:
        endpoint: API endpoint to call
    
    Returns:
        API response or error message
    """
    try:
        response = requests.get(f"https://api.example.com/{endpoint}")
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        return f"API call failed: {str(e)}"

4. Use Specific Parameter Names

# Good - Clear parameter names
def send_email(to_address: str, subject: str, body: str) -> str:
    """Send an email"""
    pass

# Bad - Vague parameter names
def send_email(to: str, s: str, b: str) -> str:  # ❌ Unclear
    pass

5. Return Structured Data When Possible

from typing import Dict, Any
import json

def get_user_info(user_id: str) -> str:
    """
    Get user information.
    
    Args:
        user_id: The user's ID
    
    Returns:
        JSON string with user information
    """
    user_data = {
        "id": user_id,
        "name": "John Doe",
        "email": "john@example.com"
    }
    return json.dumps(user_data, indent=2)

Next Steps

ToolManager

How the agent sets up, runs, and retries its tools

Dynamic Tool Loading

Defer tool schemas behind a searchable catalog

Agent Skills

Learn about the Agent Skills system

Structured Outputs

Get structured responses from agents

Reference

Tool setup, execution, and retries: swarms/agents/tool_manager.py (ToolManager)
BaseTool class: swarms/tools/base_tool.py
Function schema generation: swarms/tools/py_func_to_openai_func_str.py

​Basic Tool Usage

​Define a Simple Tool

​Tool Requirements

​Type Hints and Docstrings

​How the schema is built

​Multiple Tools

​Add Multiple Tools to an Agent

​Real-World Tool Examples

​Web Search Tool

​Database Query Tool

​File Operations Tool

​Tool Configuration

​Tool Schema Control

​Adding tools after construction

​Advanced Tool Patterns

​Tool with State

​Async Tools

​BaseTool API

​MCP Tools

​Sub-agents in autonomous mode

​Best Practices

​1. Always Include Type Hints

​2. Write Descriptive Docstrings

​3. Handle Errors Gracefully

​4. Use Specific Parameter Names

​5. Return Structured Data When Possible

​Next Steps

ToolManager

Dynamic Tool Loading

Agent Skills

Structured Outputs

​Reference

Basic Tool Usage

Define a Simple Tool

Tool Requirements

Type Hints and Docstrings

How the schema is built

Multiple Tools

Add Multiple Tools to an Agent

Real-World Tool Examples

Web Search Tool

Database Query Tool

File Operations Tool

Tool Configuration

Tool Schema Control

Adding tools after construction

Advanced Tool Patterns

Tool with State

Async Tools

BaseTool API

MCP Tools

Sub-agents in autonomous mode

Best Practices

1. Always Include Type Hints

2. Write Descriptive Docstrings

3. Handle Errors Gracefully

4. Use Specific Parameter Names

5. Return Structured Data When Possible

Next Steps

Reference