Tools and actions

Tools are functions that agents can call to interact with the world. They are the bridge between thinking and doing.

Common Tool Categories:

The schema tells the agent what a tool does and how to use it. A well-designed schema reduces errors and improves tool selection.

"""
Tool Schema Design
==================
How to define tools that agents can use effectively.
"""

from dataclasses import dataclass
from typing import Any, Dict, Callable


@dataclass
class Tool:
    """
    A tool that an AI agent can use.
    
    Attributes:
        name: Unique identifier (use snake_case)
        description: What the tool does (be specific!)
        function: The Python function to execute
        parameters: JSON Schema defining expected inputs
    """
    name: str
    description: str
    function: Callable
    parameters: Dict[str, Any]
    
    def to_prompt_format(self) -> str:
        """Format for inclusion in agent prompts."""
        params = ", ".join(
            f"{k}: {v.get('description', 'no description')}"
            for k, v in self.parameters.get("properties", {}).items()
        )
        return f"- {self.name}({params}): {self.description}"


# Example: Well-designed tool

def search_web(query: str, num_results: int = 5) -> dict:
    """Search the web and return results."""
    # Implementation would go here
    return {"results": []}


search_tool = Tool(
    name="search_web",
    description="Search the internet for current information. Use for facts, news, or data you do not know. Returns titles, snippets, and URLs.",
    function=search_web,
    parameters={
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The search query. Be specific and include relevant keywords."
            },
            "num_results": {
                "type": "integer",
                "description": "Number of results to return (1-10)",
                "default": 5
            }
        },
        "required": ["query"]
    }
)

Tool Description Best Practices:

1. Be specific: "Search the internet for current information" is better than "Search"

2. Explain when to use it: "Use for facts, news, or data you do not know"

3. Describe outputs: "Returns titles, snippets, and URLs"

4. Mention limitations: If the tool only works for certain inputs, say so

Never trust agent-generated inputs. Always validate.

"""
Tool Input Validation
=====================
Validate inputs before executing tools.
"""

from typing import Any, Optional, Tuple
import re


class ToolInputValidator:
    """Validates tool inputs before execution."""
    
    @staticmethod
    def validate_search_query(query: Any) -> Tuple[bool, Optional[str]]:
        """
        Validate a search query.
        
        Args:
            query: The query to validate
            
        Returns:
            Tuple of (is_valid, error_message)
        """
        # Must be a string
        if not isinstance(query, str):
            return False, "Query must be a string"
        
        # Must not be empty
        if not query.strip():
            return False, "Query cannot be empty"
        
        # Length limits
        if len(query) > 500:
            return False, "Query too long (max 500 characters)"
        
        # No potential injection patterns
        suspicious = [
            r"<script",
            r"javascript:",
            r"data:",
            r"vbscript:",
        ]
        for pattern in suspicious:
            if re.search(pattern, query, re.IGNORECASE):
                return False, "Query contains suspicious content"
        
        return True, None
    
    @staticmethod
    def validate_file_path(path: Any, allowed_dirs: list) -> Tuple[bool, Optional[str]]:
        """
        Validate a file path is within allowed directories.
        
        Args:
            path: The file path to validate
            allowed_dirs: List of allowed directory prefixes
            
        Returns:
            Tuple of (is_valid, error_message)
        """
        import os
        
        if not isinstance(path, str):
            return False, "Path must be a string"
        
        # Normalise path to prevent directory traversal
        normalised = os.path.normpath(os.path.abspath(path))
        
        # Check if within allowed directories
        for allowed in allowed_dirs:
            if normalised.startswith(os.path.abspath(allowed)):
                return True, None
        
        return False, f"Path not in allowed directories: {allowed_dirs}"