tool

Overview ¶

Package tool provides type definitions for tool metadata.

Package tool provides a unified and extensible tool management system for the assistant.

This package allows the assistant to perform actions beyond generating text, such as searching the web, interacting with the file system, or connecting to external services.

Key Features:

- Unified Registry: All tools, whether built-in or dynamically loaded, are registered and managed through a central `Manager`.

- Dynamic Execution: The assistant can dynamically decide which tool to use based on the user's query. The manager handles the execution and returns the result in a standardized format.

- Built-in Tools: A set of essential tools for common tasks (file I/O, web fetching) are provided out of the box.

- MCP Integration: The system is designed to integrate seamlessly with the Model Context Protocol (MCP), allowing it to discover and use external tools without requiring code changes.

- Natural Language Access: The tool schemas are provided to the LLM, allowing it to understand how to use the tools and formulate the necessary arguments from a natural language query.

Package tool implements a flexible and extensible tool system that enhances the AI assistant's capabilities beyond pure conversation.

The tool system follows Go's philosophy of simplicity and composition, providing a unified interface for diverse functionalities while maintaining clear boundaries and explicit error handling.

Architecture ¶

The tool system is built around a simple but powerful abstraction:

┌─────────────────────────────────────────────┐
│                Tool Manager                 │
├─────────────┬─────────────┬─────────────────┤
│   File I/O  │     Web     │    Memory       │
├─────────────┼─────────────┼─────────────────┤
│   Search    │    Fetch    │    Delete       │
│   Read      │   Scrape    │   Resolve       │
│   Write     │             │   Conflicts     │
└─────────────┴─────────────┴─────────────────┘

Each tool implements a common interface, allowing the assistant to discover and use tools dynamically based on user needs.

Core Concepts ¶

**Tool Interface**: Every tool implements this simple interface:

• Name(): Returns the tool's unique identifier
• Description(): Provides human-readable functionality description
• InputSchema(): Defines expected parameters as JSON Schema
• Execute(): Performs the tool's action with given inputs

**Tool Manager**: Central registry that:

• Maintains a thread-safe registry of available tools
• Handles tool discovery and execution
• Provides consistent error handling
• Manages tool configuration

**Tool Categories**:

• File System: Read, write, search local files
• Web: Fetch URLs, search the web, scrape content
• Memory: Manage the assistant's memory system
• System: Access system information and history
• Time: Date and time utilities
• UI: User interface interactions (CLI-specific)

Usage Pattern ¶

// Create manager with configuration
manager := tool.NewManager(tool.Config{
    FileSystem: tool.FileSystemConfig{
        AllowedPaths: []string{"/home/user"},
    },
})

// Register built-in tools
manager.RegisterFileTools()
manager.RegisterWebTools(webService)

// Execute a tool
result, err := manager.Execute(ctx, "file_read", map[string]any{
    "path": "/home/user/document.txt",
})

Tool Development ¶

Creating a new tool is straightforward:

type MyTool struct {
    tool.Info  // Embed for common functionality
}

func (t *MyTool) Execute(ctx context.Context, input any) (any, error) {
    // Parse input, perform action, return result
    return result, nil
}

Input Validation ¶

Tools use JSON Schema for input validation, providing:

• Type safety without reflection overhead
• Clear parameter documentation
• Automatic validation before execution
• Better error messages for users

Error Handling ¶

Following Go's explicit error handling:

• Tools return errors with context
• Transient vs permanent failures are distinguished
• User-friendly error messages are provided
• Stack traces are available for debugging

Security Considerations ¶

The tool system implements several security measures:

• File system access is restricted to allowed paths
• Web requests have timeouts and size limits
• Input validation prevents injection attacks
• Sensitive operations require explicit configuration

Integration with AI ¶

Tools are automatically discovered by the AI assistant:

• Tool descriptions are included in the system prompt
• The AI determines when to use tools based on user intent
• Results are formatted for optimal AI comprehension
• Errors are handled gracefully without breaking conversation flow

Thread Safety ¶

The Manager and all built-in tools are safe for concurrent use. Custom tools should follow the same pattern, avoiding shared mutable state.

Package tool provides type-safe tool implementations.

Package tool provides a unified interface for AI tool execution.

This package defines the core Tool interface and common functionality for all tools in the system. Tools are the bridge between AI reasoning and real-world actions, enabling the AI to perform tasks like file operations, web searches, calculations, and more.

Package tool provides type definitions for tool execution.

Package tool provides validation utilities for tool inputs.