Tools

Reference for the Agentor tools system: function decorators, BaseTool classes, and global tool registry to extend agent capabilities.

Overview

Agentor provides multiple ways to create tools that agents can use to interact with external systems, APIs, and data sources. Tools enable agents to perform actions beyond text generation.

Tool Decorators

@tool

The @tool decorator creates dual-mode tools usable by both Agentor agents and the LLM client.

from agentor import tool

@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"The weather in {city} is sunny and 72°F"

Signature:

@tool
def tool(
    func: Optional[Callable] = None,
    *,
    name: Optional[str] = None,
    description: Optional[str] = None,
) -> BaseTool

Parameters:

• name (str): Optional custom tool name (defaults to function name)
• description (str): Optional description (defaults to docstring)

Example with custom name:

@tool(name="weather_lookup", description="Fetches weather data")
def get_weather(city: str) -> str:
    return f"Weather in {city}: Sunny"

@function_tool

The @function_tool decorator creates tools compatible with the OpenAI function calling format.

from agentor import function_tool

@function_tool
def calculate(expression: str) -> float:
    """Evaluate a mathematical expression."""
    return eval(expression)

Parameters:

• name_override (str): Optional custom name for the tool (defaults to the function name)
• description_override (str): Optional description (defaults to the docstring summary)

Options the decorator accepted before 0.1.0 — strict_mode, failure_error_function, use_docstring_info, and the rest — are still accepted and ignored, so existing tool definitions keep importing unchanged.

Parameter descriptions come from a Google-style Args: block in the docstring. They are worth writing: without them the model sees only a type name and guesses more.

Example:

from agentor import Agentor, function_tool

@function_tool(name_override="math_calc")
def calculate(x: int, y: int, operation: str) -> int:
    """Perform basic arithmetic operations."""
    if operation == "add":
        return x + y
    elif operation == "multiply":
        return x * y
    return 0

agent = Agentor(
    name="Math Agent",
    tools=[calculate]
)

BaseTool Class

BaseTool is the base class for creating custom tools with multiple capabilities.

Basic Usage

from agentor.tools import BaseTool, capability

class WeatherTool(BaseTool):
    name = "weather"
    description = "Get weather information"
    
    def __init__(self, api_key: str):
        super().__init__(api_key=api_key)
    
    @capability
    def get_current(self, city: str) -> str:
        """Get current weather for a city."""
        return f"Current weather in {city}: Sunny, 72°F"
    
    @capability
    def get_forecast(self, city: str, days: int = 3) -> str:
        """Get weather forecast for a city."""
        return f"{days}-day forecast for {city}: Mostly sunny"

Class Definition

class BaseTool(ABC):
    name: str = "un-named-tool"
    description: str | None = None
    
    def __init__(self, api_key: Optional[str] = None):
        ...

Methods

list_capabilities

List all capabilities of the tool.

def list_capabilities() -> List[Tuple[str, FunctionType]]

Returns: List of (name, function) tuples for all capabilities

to_openai_function

Convert all capabilities to Tool objects with OpenAI-compatible schemas.

def to_openai_function() -> List[Tool]

Returns: List of agentor.engine.tools.Tool objects

json_schema

Convert all capabilities to JSON Schema format.

def json_schema() -> List[ToolType]

Returns: List of tool schemas

serve

Serve the tool as an MCP (Model Context Protocol) server.

def serve(
    name: Optional[str] = None,
    port: int = 8000
)

Parameters:

• name (str): Optional server name (defaults to tool name)
• port (int): Port to serve on (default: 8000)

Example:

weather = WeatherTool(api_key="...")
weather.serve(port=8000)  # Serves MCP server on port 8000

from_function

Create a BaseTool from a standalone function.

@staticmethod
def from_function(
    func: Callable,
    name: str | None = None,
    description: str | None = None
) -> BaseTool

Example:

from agentor.tools.base import BaseTool

def weather_tool(city: str) -> str:
    """Get weather for a city."""
    return f"Weather in {city} is warm and sunny."

tool = BaseTool.from_function(weather_tool)
result = tool.run("London")
print(result)  # "Weather in London is warm and sunny."

@capability Decorator

Mark a method as a tool capability that agents can invoke.

from agentor.tools.base import capability

@capability
def my_capability(self, param: str) -> str:
    """Capability description."""
    return f"Result: {param}"

Using Tools with Agents

Function Tools

from agentor import Agentor, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Returns the weather in the given city."""
    return f"The weather in {city} is sunny"

agent = Agentor(
    name="Weather Assistant",
    tools=[get_weather],
    instructions="Use the weather tool to answer questions."
)

result = agent.run("What's the weather in Tokyo?")

BaseTool Instances

from agentor import Agentor
from agentor.tools import GetWeatherTool

weather_tool = GetWeatherTool(api_key="your_api_key")

agent = Agentor(
    name="Weather Agent",
    tools=[weather_tool],
    instructions="Always use the weather tool to answer weather questions."
)

result = agent.run("What is the current weather in London?")

Tool Registry

A small set of built-in tools can be referenced by string name:

from agentor import Agentor

agent = Agentor(
    name="Multi-Tool Agent",
    tools=["get_weather", "current_datetime"],  # Reference by name
    instructions="Use the available tools to help the user."
)

The registry holds exactly two names today: get_weather and current_datetime. Any other string raises ValueError: Tool <name> not found. Every other built-in — Gmail, GitHub, Slack, and the rest — is a class you import and instantiate.

MCP Servers

import os
from agentor import Agentor
from agentor.mcp import MCPServer

mcp_server = MCPServer(
    url="https://api.example.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    timeout=10,
    name="Search Server",
)

agent = Agentor(
    name="Search Agent",
    tools=[mcp_server],
    instructions="Use the search tool to find information."
)

The agent connects to the server for the duration of each run and closes it afterwards. See the MCP guide for details.

Built-in Tools

Agentor includes several built-in tools:

Calculator Tool

from agentor import Agentor
from agentor.tools import CalculatorTool

agent = Agentor(
    name="Math Assistant",
    tools=[CalculatorTool()],
    instructions="Use the calculator for all arithmetic."
)

result = agent.run("What is (37 * 12) - (144 / 3)?")

Weather Tool

import os
from agentor import Agentor
from agentor.tools import GetWeatherTool

weather_api_key = os.environ.get("WEATHER_API_KEY")

agent = Agentor(
    name="Weather Agent",
    tools=[GetWeatherTool(api_key=weather_api_key)],
    instructions="Provide accurate weather information."
)

Tool Examples

Simple Function Tool

from agentor import Agentor, function_tool
import datetime

@function_tool
def get_current_time(timezone: str = "UTC") -> str:
    """Get the current time in a specific timezone."""
    return f"Current time in {timezone}: {datetime.datetime.now()}"

agent = Agentor(
    name="Time Assistant",
    tools=[get_current_time]
)

Multi-Capability Tool

from agentor.tools import BaseTool, capability
import requests

class APItool(BaseTool):
    name = "api_client"
    description = "Make HTTP API requests"
    
    @capability
    def get(self, url: str) -> str:
        """Make a GET request."""
        response = requests.get(url)
        return response.text
    
    @capability
    def post(self, url: str, data: dict) -> str:
        """Make a POST request."""
        response = requests.post(url, json=data)
        return response.text

api_tool = APItool()

Tool with State

from agentor.tools import BaseTool, capability

class CounterTool(BaseTool):
    name = "counter"
    description = "Track and increment a counter"
    
    def __init__(self):
        super().__init__()
        self.count = 0
    
    @capability
    def increment(self, amount: int = 1) -> str:
        """Increment the counter."""
        self.count += amount
        return f"Counter is now: {self.count}"
    
    @capability
    def get_count(self) -> str:
        """Get the current count."""
        return f"Current count: {self.count}"
    
    @capability
    def reset(self) -> str:
        """Reset the counter to zero."""
        self.count = 0
        return "Counter reset to 0"

Tool from Function

from agentor.tools.base import BaseTool

def search_database(query: str) -> str:
    """Search the database for records."""
    # Implementation here
    return f"Found 5 results for: {query}"

search_tool = BaseTool.from_function(
    search_database,
    name="db_search",
    description="Search database records"
)

result = search_tool.run("user accounts")

Best Practices

1. Clear Descriptions: Always provide clear docstrings - they become tool descriptions for the LLM
2. Type Hints: Use type hints for all parameters and return values
3. Error Handling: Handle errors gracefully within tool functions
4. Focused Tools: Keep tools focused on specific tasks
5. Idempotent Operations: Make tools safe to retry when possible
6. Documentation: Document expected inputs and outputs

from agentor import function_tool
from typing import Optional

@function_tool
def get_user_profile(user_id: str, include_history: bool = False) -> str:
    """
    Retrieve a user's profile information.
    
    Args:
        user_id: The unique identifier for the user
        include_history: Whether to include purchase history (default: False)
    
    Returns:
        JSON string containing user profile data
    """
    try:
        # Implementation
        return '{"name": "Alice", "email": "[e-mail]"}'
    except Exception as e:
        return f"Error fetching user profile: {str(e)}"

Related

• Agentor - Using tools with agents
• LLM - Direct LLM usage with tools