Tool System Refactoring - Auto-Discovery & Simplified Architecture

Overview

The tool system has been refactored to be auto-generated and self-documenting, eliminating the need for manual maintenance of tool metadata across multiple files.

What Changed

✅ New Features

1. Metadata Decorators (backend/core/agentpress/tool.py)

   • @tool_metadata() - Add display name, description, icon, and color to tool classes
   • @method_metadata() - Add display name and description to tool methods
   • Tools can now be self-documenting

2. Auto-Discovery System (backend/core/utils/tool_discovery.py)

   • Automatically scans backend/core/tools/ directory
   • Discovers all Tool subclasses
   • Extracts metadata from decorators and schemas
   • Generates default metadata for tools without decorators
   • No manual registration needed!

3. Tools API (backend/core/tools_api.py)

   • GET /tools - Returns all tools with metadata
   • GET /tools/{tool_name} - Returns specific tool metadata
   • Frontend can fetch tool information dynamically

4. React Hook (frontend/src/hooks/react-query/tools/use-tools-metadata.ts)

   • useToolsMetadata() - Fetch all tools from API
   • useToolMetadata(toolName) - Fetch specific tool
   • Cached for performance

🗑️ Deprecated (Can Now Be Removed)

• backend/core/utils/tool_groups.py - Replaced by auto-discovery

  • Manual maintenance of 971 lines of tool metadata
  • Duplicated information that's already in tool classes

• frontend/src/components/agents/tools/tool-groups-comprehensive.ts - Can fetch from API instead

  • 1000+ lines of static tool metadata
  • Now fetched dynamically from backend

Benefits

Before

# Had to manually update tool_groups.py every time a tool changed
TOOL_GROUPS = {
    "sb_files_tool": ToolGroup(
        name="sb_files_tool",
        display_name="File Operations",
        description="Create, read, edit...",
        # ... 50+ lines per tool
    ),
    # ... repeated for every tool
}

After

# Tool defines its own metadata
@tool_metadata(
    display_name="File Operations",
    description="Create, read, edit, and manage files",
    icon="FolderOpen",
    color="bg-blue-100 dark:bg-blue-800/50"
)
class SandboxFilesTool(Tool):
    
    @method_metadata(
        display_name="Create File",
        description="Create new files with content"
    )
    @openapi_schema({...})
    def create_file(self, ...):
        ...

Usage

Adding a New Tool

Simply create a tool class that inherits from Tool. It will be automatically discovered!

from core.agentpress.tool import Tool, tool_metadata, method_metadata, openapi_schema

@tool_metadata(
    display_name="My Awesome Tool",
    description="Does awesome things",
    icon="Sparkles",
    color="bg-purple-100 dark:bg-purple-800/50"
)
class MyAwesomeTool(Tool):
    
    @method_metadata(
        display_name="Do Something",
        description="Does something awesome"
    )
    @openapi_schema({
        "type": "function",
        "function": {
            "name": "do_something",
            "description": "Does something awesome",
            "parameters": {...}
        }
    })
    def do_something(self, param: str):
        return self.success_response("Done!")

That's it! The tool will:

• ✅ Be automatically discovered
• ✅ Appear in the API response
• ✅ Be available in the frontend
• ✅ Have proper metadata for UI display

Using the API

# Backend - Get all tools
from core.utils.tool_discovery import get_tools_metadata

tools = get_tools_metadata()
# Returns: {"sb_files_tool": {...}, "sb_shell_tool": {...}, ...}

// Frontend - Use React hook
import { useToolsMetadata } from '@/hooks/react-query/tools/use-tools-metadata';

function MyComponent() {
  const { data, isLoading } = useToolsMetadata();
  
  if (data?.success) {
    const tools = data.tools;
    // All tool metadata available here
  }
}

Migration Notes

For Backend Developers

• No changes needed for existing tools - they'll work without decorators
• Recommended: Add decorators for better UI experience
• Don't edit: tool_groups.py is now deprecated

For Frontend Developers

• Old way (static): import { TOOL_GROUPS } from './tool-groups-comprehensive'
• New way (dynamic): const { data } = useToolsMetadata()
• Existing code using TOOL_GROUPS still works for now

File Summary

New Files

• backend/core/agentpress/tool.py - Enhanced with metadata decorators
• backend/core/utils/tool_discovery.py - Auto-discovery system
• backend/core/tools_api.py - API endpoints
• frontend/src/hooks/react-query/tools/use-tools-metadata.ts - React hook

✅ Removed Legacy Files

• ✅ backend/core/utils/tool_groups.py - 971 lines DELETED (replaced by auto-discovery)
• ✅ frontend/src/components/agents/tools/tool-groups-comprehensive.ts - 1069 lines DELETED (fetch from API)

Savings

• ~2040 lines of duplicated code ELIMINATED ✨
• Zero manual maintenance for tool metadata
• Single source of truth - tool classes define their own metadata

Naming Convention

Important: The naming remains agentpress_tools throughout the codebase for consistency:

• Database: config.tools.agentpress
• Python code: agentpress_tools
• API responses: agentpress_tools

This was kept to maintain backward compatibility and avoid breaking changes.