Tools API Reference

This section provides detailed API documentation for the MailOS tool system.

Tool Base

class mailos.vendors.models.Tool(name: str, description: str, parameters: Dict, function: Callable, required_params: List[str] = None)[source]

Represents a tool or function that can be called by the LLM.

name: str
description: str
parameters: Dict
function: Callable
required_params: List[str] = None
to_dict() Dict[source]

Convert tool to a dictionary.

__init__(name: str, description: str, parameters: Dict, function: Callable, required_params: List[str] = None) None

Built-in Tools

Weather Tool

mailos.tools.weather.get_weather(city: str) Dict[source]

Get current weather for a given city using OpenWeatherMap API.

Parameters:

city – Name of the city to get weather for

Returns:

Dict containing weather data or error message

mailos.tools.weather.weather_tool = Tool instance for weather information

Represents a tool or function that can be called by the LLM.

Python Interpreter

mailos.tools.python_interpreter.execute_python(code: str, timeout: int = 5) Dict[source]

Execute Python code and return the output.

Parameters:
  • code – Python code to execute

  • timeout – Maximum execution time in seconds (default: 5)

Returns:

Dict with execution status, output/error, and any printed output

mailos.tools.python_interpreter.python_interpreter_tool = Tool instance for Python code execution

Represents a tool or function that can be called by the LLM.

Bash Command

mailos.tools.bash_command.bash_command_tool = Tool instance for bash command execution

Represents a tool or function that can be called by the LLM.

Tool Registry

mailos.tools.AVAILABLE_TOOLS = List of available tools

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Tool Utilities

mailos.utils.logger_utils.setup_logger(name, log_level=20)[source]

Set up logger for a given name (deprecated).

Common Tool Patterns

Error Handling

Tools should follow this error handling pattern:

def my_tool_function(param: str) -> Dict:
    try:
        # Tool implementation
        return {
            "status": "success",
            "data": result
        }
    except Exception as e:
        logger.error(f"Error: {str(e)}")
        return {
            "status": "error",
            "message": str(e)
        }

Response Format

Success Response:

{
    "status": "success",
    "data": {
        # Tool-specific data
    }
}

Error Response:

{
    "status": "error",
    "message": "Error description"
}

Tool Configuration

Tools can be configured using:

  1. Environment variables

  2. Tool-specific configuration in email_config.json

  3. Runtime parameters passed to the tool function

Example Configuration:

{
    "checkers": [{
        "enabled_tools": ["weather", "python_interpreter"],
        "tool_config": {
            "weather": {
                "default_units": "metric"
            },
            "python_interpreter": {
                "timeout": 30,
                "max_memory": 128
            }
        }
    }]
}