Reference Documentation

This section provides detailed reference information for tool development in ToolUniverse.

Architecture

Understanding the internal architecture of ToolUniverse helps you build better tools and integrate more effectively with the system.

I want to understand the overall architecture: → ToolUniverse Architecture - System architecture and design patterns

I want to compare tool types: → Review the tool type comparison table in Contributing to ToolUniverse

Tool Comparison

Understanding the differences between local and remote tools helps you choose the right approach for your needs.

Key Differences:

Aspect | Local Tools | Remote Tools |

|--------|————-|--------------| | Performance | High (no network overhead) | Lower (network latency) | | Development | Simple Python classes | MCP servers or API wrappers | | Deployment | Part of ToolUniverse | Independent servers | | Scalability | Limited by process | Highly scalable | | Integration | Full ToolUniverse access | Limited to MCP/API | | Contribution | Requires __init__.py changes | No code changes needed |

When to Use Local Tools: - Data processing and analysis - File manipulation utilities - Simple API wrappers - Tools that need full ToolUniverse integration

When to Use Remote Tools: - External service integration - Heavy computational tasks - Microservice architecture - Tools in different programming languages

Architecture Details

ToolUniverse Core Components: - Tool Registry: Manages tool discovery and registration - Execution Engine: Handles tool execution and error management - Configuration System: Manages tool parameters and settings - MCP Integration: Connects with remote tools via MCP protocol

Tool Lifecycle: 1. Registration: Tools register with the registry 2. Discovery: ToolUniverse discovers available tools 3. Configuration: Tools load their configuration 4. Execution: Tools are called with parameters 5. Response: Results are returned to the caller

Error Handling: - Input validation at multiple levels - Graceful error recovery - Comprehensive error reporting - Timeout management for remote tools

Best Practices

Local Tools: - Keep tools focused and single-purpose - Use proper error handling - Implement input validation - Add comprehensive tests - Document all parameters clearly

Remote Tools: - Implement proper authentication - Use circuit breakers for resilience - Add retry logic for transient failures - Monitor performance and errors - Provide clear deployment documentation

General: - Follow naming conventions - Use descriptive parameter names - Provide clear error messages - Include usage examples - Test with real-world data

Troubleshooting

Common Issues:

Local Tools: - Tool not found: Check registration and imports - Parameter errors: Verify JSON schema - Execution failures: Check BaseTool inheritance - Import errors: Verify module structure

Remote Tools: - Connection errors: Check server URL and network - Authentication failures: Verify credentials - Timeout issues: Check server performance - Discovery problems: Verify MCP server status

General: - Configuration errors: Check JSON syntax - Permission issues: Verify file access - Version conflicts: Check dependencies - Performance issues: Profile and optimize

Resources

Next Steps

Ready to dive deeper? Choose your focus:

Tip

Reference First: Understanding the architecture and differences between tool types will help you make better decisions about which approach to use for your specific needs.