Tool Management Guide¶
This guide covers everything you need to know about managing tools in MailOS.
Tool System Architecture¶
graph TB LLM[LLM System] --> |Uses| ToolRegistry[Tool Registry] ToolRegistry --> |Manages| Tools[Available Tools] Tools --> Weather[Weather Tool] Tools --> PDF[PDF Tool] Tools --> Python[Python Interpreter] Tools --> Bash[Bash Command] subgraph Tool Implementation Weather --> |Uses| WeatherAPI[Weather API] PDF --> |Uses| PDFLib[PDF Library] Python --> |Uses| PyInterp[Python Runtime] Bash --> |Uses| Shell[Shell Environment] end subgraph Configuration Config[Config File] --> |Configures| Tools EnvVars[Environment Variables] --> |Configures| Tools end subgraph Error Handling Tools --> |Returns| Success[Success Response] Tools --> |Returns| Error[Error Response] Logger[Logger] --> |Records| Error end
Tool Structure¶
A typical tool consists of:
src/mailos/tools/
├── __init__.py # Tool registry
├── weather.py # Weather tool implementation
├── python_interpreter.py # Python code execution tool
└── bash_command.py # Bash command execution tool
Creating New Tools¶
Create a new file in
src/mailos/tools/
Define your tool function
Create a Tool instance
Register the tool in
__init__.py
Example Implementation¶
from typing import Dict
from mailos.vendors.models import Tool
from mailos.utils.logger_utils import logger
def my_tool_function(param1: str) -> Dict:
"""Implement your tool's functionality."""
try:
# Tool implementation
result = {"status": "success", "data": "result"}
return result
except Exception as e:
logger.error(f"Tool error: {str(e)}")
return {"status": "error", "message": str(e)}
# Define tool interface
my_tool = Tool(
name="my_tool",
description="Description of what the tool does",
parameters={
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Parameter description",
}
},
},
required_params=["param1"],
function=my_tool_function,
)
Tool Registration¶
In src/mailos/tools/__init__.py
:
from .my_tool import my_tool
AVAILABLE_TOOLS = [
("my_tool", "My Tool Display Name"),
# Other tools...
]
Tool Dependencies¶
Add dependencies to
pyproject.toml
:
[project]
dependencies = [
"existing-dep>=1.0.0",
"my-tool-dep>=2.0.0", # Add your tool's dependencies
]
Document dependencies in tool’s docstring
Update installation instructions
Configuration¶
Tools can be configured through:
Environment variables
Configuration files
Runtime parameters
Example Configuration¶
import os
from dotenv import load_dotenv
# Load configuration
load_dotenv()
# Get configuration
API_KEY = os.getenv("MY_TOOL_API_KEY")
BASE_URL = os.getenv("MY_TOOL_BASE_URL", "default-url")
Testing¶
Create test file in
tests/tools/
:
import pytest
from mailos.tools.my_tool import my_tool_function
def test_my_tool_success(mock_dependency):
"""Test successful tool execution."""
result = my_tool_function("test_param")
assert result["status"] == "success"
assert "data" in result
def test_my_tool_error_handling():
"""Test tool error handling."""
result = my_tool_function("invalid_param")
assert result["status"] == "error"
assert "message" in result
Add fixtures in
tests/conftest.py
Run tests:
pytest tests/tools/test_my_tool.py
Best Practices¶
Naming Conventions¶
Tool files: lowercase with underscores (e.g.,
my_tool.py
)Functions: lowercase with underscores
Classes: PascalCase
Constants: UPPERCASE with underscores
Documentation¶
Docstrings for all public functions
Type hints for parameters and returns
Example usage in docstrings
Clear error messages
Error Handling¶
Always return a dict with “status” and “data”/”message”
Log errors with appropriate level
Provide helpful error messages
Handle expected exceptions gracefully
Tool Lifecycle¶
stateDiagram-v2 [*] --> Development Development --> Testing: Implement Testing --> Review: Pass Tests Review --> Integration: Approved Integration --> Production: Deploy Production --> Maintenance: Monitor Maintenance --> Deprecated: Obsolete Deprecated --> [*]: Remove
Troubleshooting¶
Common Issues¶
Tool not appearing in UI * Check registration in
__init__.py
* Verify tool name matches registrationDependencies not found * Ensure dependencies in
pyproject.toml
* Check virtual environment activationConfiguration errors * Verify environment variables * Check configuration file format
Debug Procedures¶
Enable debug logging:
import logging
logging.getLogger("mailos").setLevel(logging.DEBUG)
Check tool registration:
from mailos.tools import AVAILABLE_TOOLS
print(AVAILABLE_TOOLS)
Test tool directly:
from mailos.tools.my_tool import my_tool_function
result = my_tool_function("test")
print(result)
Removing Tools¶
Remove tool file
Remove from
__init__.py
Remove tests
Update documentation
Remove dependencies if no longer needed
Update version number
Version Management¶
Use semantic versioning
Document breaking changes
Maintain backwards compatibility when possible
Update documentation for new versions
Security Considerations¶
Validate all inputs
Use environment variables for sensitive data
Implement rate limiting if needed
Follow security best practices for external APIs
Regular security audits
See Also¶
Tools API Reference for API reference
Configuration Guide for configuration options
Quickstart Guide for getting started