Skip to main content

Tool Integration Cookbook

Patterns and Recipes for Agentic Tool Systems​

Document ID: A3-TOOL-COOKBOOK
Version: 1.0
Category: P1 - Implementation Guides

Tool Architecture Overview​

┌─────────────────────────────────────────────────────────────┐
│                    TOOL REGISTRY                             │
│  (Tool definitions, schemas, capabilities)                   │
├─────────────────────────────────────────────────────────────┤
│                    TOOL SELECTOR                             │
│  (Intent matching, tool ranking, selection logic)            │
├─────────────────────────────────────────────────────────────┤
│                    TOOL EXECUTOR                             │
│  (Validation, sandboxing, execution, result capture)         │
├─────────────────────────────────────────────────────────────┤
│                    RESULT PROCESSOR                          │
│  (Parsing, transformation, error handling)                   │
└─────────────────────────────────────────────────────────────┘

Tool Definition Framework​

class ToolCategory(Enum):
    KNOWLEDGE = "knowledge"      # Retrieval, search
    ACTION = "action"            # External modifications
    COMPUTE = "compute"          # Calculations
    COMMUNICATION = "communication"

@dataclass
class ToolDefinition:
    name: str
    description: str
    category: ToolCategory
    parameters: List[ToolParameter]
    timeout_seconds: int = 30
    max_retries: int = 3
    requires_confirmation: bool = False
    risk_level: str = "low"  # low, medium, high
    reversible: bool = True

Knowledge Tools​

class WebSearchTool(Tool):
    parameters = [
        {"name": "query", "type": "string"},
        {"name": "num_results", "type": "number", "default": 5},
        {"name": "time_range", "type": "string", "enum": ["day", "week", "month"]}
    ]
    
    async def execute(self, query, num_results, time_range):
        # Tavily, Serper, or similar
        return {"results": [...], "query": query}
class VectorSearchTool(Tool):
    parameters = [
        {"name": "query", "type": "string"},
        {"name": "collection", "type": "string"},
        {"name": "top_k", "type": "number", "default": 5},
        {"name": "min_score", "type": "number", "default": 0.7}
    ]

Database Query​

class DatabaseQueryTool(Tool):
    # Read-only SQL queries
    # Block dangerous keywords (DROP, DELETE, etc.)
    # Apply LIMIT automatically

Action Tools​

API Call​

class APICallTool(Tool):
    parameters = [
        {"name": "endpoint", "type": "string"},
        {"name": "method", "type": "string", "enum": ["GET", "POST", "PUT"]},
        {"name": "body", "type": "object"}
    ]
    requires_confirmation = True  # For non-GET

CRM Update​

class CRMUpdateTool(Tool):
    # Create, update, delete CRM records
    # Stores rollback data for reversibility
    async def rollback(self, execution_id):
        # Reverse the operation

File Operations​

class FileOperationsTool(Tool):
    # Sandboxed to workspace_root
    # Allowed extensions only
    # Rollback support for writes

Compute Tools​

Calculator​

class CalculatorTool(Tool):
    # Safe eval with math functions only
    # Block dangerous operations

Code Execution​

class CodeExecutionTool(Tool):
    # Docker or E2B sandbox
    # Resource limits (memory, CPU, network)
    # Timeout enforcement

Data Transform​

class DataTransformTool(Tool):
    operations = ["filter", "sort", "aggregate", "pivot", "parse_json"]

Communication Tools​

Email​

class EmailTool(Tool):
    requires_confirmation = True
    reversible = False

Slack​

class SlackTool(Tool):
    # Channel messages, threads
    # Low risk, no confirmation needed

Tool Executor​

class ToolExecutor:
    async def execute(self, tool_name, params, session_id):
        tool = self.registry.get(tool_name)
        
        # Validate parameters
        if not await tool.validate_params(**params):
            return {"success": False, "error": "Invalid parameters"}
        
        # Confirmation if required
        if tool.requires_confirmation:
            if not await self.confirmation_handler(tool_name, params):
                return {"success": False, "error": "User declined"}
        
        # Execute with retry
        for attempt in range(tool.max_retries):
            try:
                result = await asyncio.wait_for(
                    tool.execute(**params),
                    timeout=tool.timeout_seconds
                )
                await self.audit_log.log_action(...)
                return result
            except (TimeoutError, Exception) as e:
                last_error = str(e)
        
        return {"success": False, "error": last_error}

Tool Selection Patterns​

Intent-Based​

# Embed query and tool descriptions
# Calculate similarity scores
# Return top matching tools

Category-Based​

task_to_categories = {
    "research": [KNOWLEDGE],
    "analysis": [KNOWLEDGE, COMPUTE],
    "action": [ACTION],
    "automation": [ACTION, COMPUTE]
}

Tool Patterns by Paradigm​

ParadigmPrimary ToolsStrategy
LSRNone/CalculatorMinimal tool use
GSKnowledge search, DB queryHeavy retrieval
EPAll categoriesAdaptive selection
VEAction toolsProtocol-driven

Safety Controls​

ControlImplementation
Input validationSchema validation, sanitization
SandboxingDocker, E2B for code execution
Rate limitingPer-tool, per-session limits
ConfirmationHuman approval for risky actions
Audit loggingEvery execution logged
RollbackStore undo data when possible

Document maintained by CODITECT Integration Team