@falai/agent 0.9.0 → 0.9.2

package/docs/core/tools/tool-definition.md

@@ -1,26 +1,86 @@
-# Tool Definition
+# Tool Definition with Unified Interface
 
-Tools in @falai/agent enable AI agents to execute custom logic, access external APIs, and perform actions during conversations. This document covers tool creation, configuration, and integration.
+Tools in @falai/agent enable AI agents to execute custom logic, access external APIs, and perform actions during conversations. The unified Tool interface supports both simple return values and complex ToolResult patterns, providing maximum flexibility with minimal complexity.
 
 ## Overview
 
-Tools provide a way for agents to:
+The unified Tool system provides:
 
-- Execute business logic and API calls
-- Access external services and databases
-- Perform calculations and data transformations
-- Update conversation context and session data
+- **Single Interface**: One Tool interface that handles both simple and advanced patterns
+- **Flexible Returns**: Return simple values (`return 'result'`) or complex objects (`return { data: 'result', success: true }`)
+- **Multiple Creation Methods**: Direct addition, registry system, pattern helpers, and manual creation
+- **Type Safety**: Full TypeScript support with automatic type inference
+- **Helper Methods**: Built-in context and data update utilities
+- **Intelligent Scoping**: Hierarchical tool resolution with registry fallback
 
-## Tool Creation
+## Unified Tool Interface
 
-Tools are created as objects implementing the `Tool` interface:
+All tools use the same interface regardless of complexity:
 
 ```typescript
-import { Tool } from "@falai/agent";
+interface Tool<TContext = unknown, TData = unknown, TResult = unknown> {
+  id: string;
+  name?: string;
+  description?: string;
+  parameters?: unknown;
+  handler: (
+    context: ToolContext<TContext, TData>,
+    args?: Record<string, unknown>
+  ) => Promise<TResult | ToolResult<TResult, TContext, TData>> | TResult | ToolResult<TResult, TContext, TData>;
+}
+```
+
+The handler can return either:
+- **Simple values**: `return 'result'` or `return { status: 'complete' }`
+- **ToolResult objects**: `return { data: 'result', success: true, contextUpdate: {...} }`
+
+```typescript
+import { Agent, GeminiProvider } from "@falai/agent";
+
+const agent = new Agent({
+  name: "Assistant",
+  provider: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY!,
+  }),
+});
+
+// Access ToolManager for advanced operations
+const toolManager = agent.tool;
+```
+
+## Tool Creation Methods
+
+The unified Tool interface supports multiple creation approaches, each optimized for different use cases:
+
+### 1. Simple Return Values (Recommended for Most Cases)
+
+The most straightforward approach - just return the result directly:
 
-const weatherTool: Tool<unknown, WeatherData, [], string> = {
+```typescript
+import { Agent, GeminiProvider } from "@falai/agent";
+
+interface UserContext {
+  userId: string;
+  preferences: Record<string, any>;
+}
+
+interface WeatherData {
+  location?: string;
+  temperature?: number;
+  condition?: string;
+}
+
+const agent = new Agent<UserContext, WeatherData>({
+  name: "Weather Assistant",
+  provider: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY!,
+  }),
+});
+
+// Simple return value - most common pattern
+agent.addTool({
   id: "get_weather",
-  name: "Weather Forecast", // Human-readable name shown to AI models
+  name: "Weather Forecast",
   description: "Get current weather and forecast for a location",
   parameters: {
     type: "object",
@@ -30,45 +90,244 @@ const weatherTool: Tool<unknown, WeatherData, [], string> = {
     },
     required: ["location"],
   },
-  handler: async ({ location, date }) => {
-    const weather = await weatherAPI.getForecast(location, date);
-    return {
-      data: `The weather in ${location} on ${date} is ${weather.condition}`,
-      contextUpdate: {
-        currentWeather: weather,
-        lastWeatherCheck: new Date().toISOString(),
-      },
-    };
+  handler: async ({ context, data, updateContext, updateData }, args) => {
+    const weather = await weatherAPI.getForecast(args.location, args.date);
+    
+    // Use helper methods for updates
+    await updateContext({ lastWeatherCheck: new Date().toISOString() });
+    await updateData({
+      location: args.location,
+      temperature: weather.temperature,
+      condition: weather.condition,
+    });
+    
+    // Return simple string - unified interface handles the rest
+    return `The weather in ${args.location} on ${args.date} is ${weather.condition}`;
   },
-};
+});
 ```
 
-## Tool Name
+### 2. Advanced ToolResult Pattern
 
-The optional `name` field provides a human-readable name for the tool that is displayed to AI models. When provided, this name takes precedence over the `id` field in AI provider interactions:
+For complex scenarios requiring detailed control:
 
 ```typescript
-const calculatorTool: Tool<unknown, CalcData, [], string> = {
-  id: "math_calculator", // Internal identifier
-  name: "Math Calculator", // Display name for AI models
+// Advanced ToolResult pattern for complex scenarios
+agent.addTool({
+  id: "process_payment",
+  name: "Payment Processor",
+  description: "Process payment with detailed result tracking",
+  parameters: {
+    type: "object",
+    properties: {
+      amount: { type: "number", description: "Payment amount" },
+      currency: { type: "string", description: "Currency code" },
+    },
+    required: ["amount", "currency"],
+  },
+  handler: async ({ context, data }, args) => {
+    try {
+      const result = await paymentAPI.process(args.amount, args.currency);
+      
+      // Return detailed ToolResult object
+      return {
+        data: `Payment of ${args.amount} ${args.currency} processed successfully`,
+        success: true,
+        contextUpdate: {
+          lastPaymentId: result.transactionId,
+          paymentHistory: [...(context.paymentHistory || []), result]
+        },
+        dataUpdate: {
+          paymentStatus: 'completed',
+          transactionId: result.transactionId
+        }
+      };
+    } catch (error) {
+      return {
+        data: `Payment failed: ${error.message}`,
+        success: false,
+        contextUpdate: {
+          lastPaymentError: error.message
+        }
+      };
+    }
+  },
+});
+```
+
+## Multiple Creation Approaches
+
+Choose the approach that best fits your use case:
+
+### 3. Direct Addition (`agent.addTool`)
+
+Add tools directly to agent scope - available to all routes and steps:
+
+```typescript
+// Creates and adds tool to agent scope in one operation
+agent.addTool({
+  id: "math_calculator",
+  name: "Math Calculator",
   description: "Perform mathematical calculations",
-  // ... rest of tool definition
-};
+  parameters: {
+    type: "object",
+    properties: {
+      expression: { type: "string", description: "Mathematical expression to evaluate" },
+    },
+    required: ["expression"],
+  },
+  handler: async ({ context, data, updateData }, args) => {
+    const result = performCalculation(args.expression);
+    
+    // Update collected data with calculation result
+    await updateData({ lastCalculation: result });
+    
+    // Simple return value
+    return `Result: ${result}`;
+  },
+});
+```
+
+### 4. Registry System (`agent.tool.register`)
+
+Register tools for reuse across multiple contexts:
+
+```typescript
+// Register tool without adding to any scope
+agent.tool.register({
+  id: "reusable_search",
+  name: "Universal Search",
+  description: "Search across multiple data sources",
+  parameters: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query" },
+      sources: { type: "array", items: { type: "string" }, description: "Data sources to search" },
+    },
+    required: ["query"],
+  },
+  handler: async ({ context, data }, args) => {
+    const results = await searchMultipleSources(args.query, args.sources);
+    return `Found ${results.length} results`; // Simple return
+  },
+});
+
+// Reference registered tool by ID in steps
+route.initialStep.nextStep({
+  prompt: "What would you like to search for?",
+  tools: ['reusable_search'] // Reference by ID
+});
+
+// Or add registered tool to specific scopes
+const searchTool = agent.tool.find('reusable_search');
+route.addTool(searchTool);
+```
+
+### 5. Manual Creation (`agent.tool.create`)
+
+Create tool instances without registering or adding to any scope:
+
+```typescript
+// Create tool instance for manual management
+const customTool = agent.tool.create({
+  id: "standalone_processor",
+  description: "Process data independently",
+  handler: async ({ context, data }) => {
+    return "Processing complete"; // Simple return
+  },
+});
+
+// Manually add to specific contexts as needed
+someStep.tools = [customTool];
+```
+
+### 6. Bulk Operations (`registerMany`)
+
+Register multiple tools at once:
+
+```typescript
+agent.tool.registerMany([
+  {
+    id: "system_status",
+    description: "Check system health",
+    handler: async () => "System OK", // Simple return
+  },
+  {
+    id: "audit_log",
+    description: "Create audit log entry",
+    handler: async ({ context }) => `Audit logged for ${context.userId}`,
+  },
+  existingToolInstance, // Can mix definitions and instances
+]);
 ```
 
-**Benefits:**
+### 7. Pattern Helpers
 
-- **Better AI Understanding**: Clear, descriptive names help AI models choose appropriate tools
-- **User-Friendly**: More readable than cryptic IDs in AI responses and logs
-- **Backward Compatible**: Falls back to `id` if `name` is not provided
-- **Flexible**: Allows separation of internal IDs from user-facing names
+Use built-in helpers for common tool patterns - these return tool instances that can be registered or added as needed:
+
+```typescript
+// Data enrichment tool - returns Tool instance
+const enrichmentTool = agent.tool.createDataEnrichment({
+  id: "enrich_user_profile",
+  fields: ['name', 'email'] as const, // Type-safe field selection
+  enricher: async (context, data) => ({
+    fullName: `${data.name} (${context.userRole})`,
+    emailDomain: data.email?.split('@')[1],
+  })
+});
+
+// Validation tool - returns Tool instance
+const validationTool = agent.tool.createValidation({
+  id: "validate_booking",
+  fields: ['date', 'guests'] as const,
+  validator: async (context, data) => {
+    const errors = [];
+    if (!data.date) errors.push({ field: 'date', message: 'Date is required' });
+    if (!data.guests || data.guests < 1) errors.push({ field: 'guests', message: 'At least 1 guest required' });
+    
+    return { valid: errors.length === 0, errors };
+  }
+});
+
+// API call tool - returns Tool instance
+const apiTool = agent.tool.createApiCall({
+  id: "fetch_weather_data",
+  endpoint: "https://api.weather.com/v1/current",
+  method: "GET",
+  headers: { "API-Key": process.env.WEATHER_API_KEY! },
+  transform: (response: any) => response.data.current,
+});
+
+// Computation tool - returns Tool instance
+const computeTool = agent.tool.createComputation({
+  id: "calculate_total_cost",
+  inputs: ['basePrice', 'taxRate', 'discountPercent'] as const,
+  compute: async (context, inputs) => {
+    const subtotal = inputs.basePrice * (1 - (inputs.discountPercent || 0) / 100);
+    return subtotal * (1 + (inputs.taxRate || 0));
+  }
+});
+
+// Register or add pattern helpers as needed
+agent.tool.registerMany([enrichmentTool, validationTool, apiTool, computeTool]);
+```
+
+## When to Use Each Approach
+
+- **Simple Return Values**: Most common cases, straightforward results
+- **ToolResult Pattern**: Complex scenarios requiring context/data updates
+- **Direct Addition**: Tools specific to one agent
+- **Registry System**: Reusable tools across multiple contexts
+- **Manual Creation**: Custom tool management scenarios
+- **Bulk Operations**: Efficient registration of multiple tools
+- **Pattern Helpers**: Common patterns with built-in logic
 
 ## Tool Parameters
 
 Tool parameters are defined using JSON Schema:
 
 ```typescript
-const searchTool: Tool<unknown, SearchData, [], string> = {
+agent.addTool({
   id: "web_search",
   name: "Web Search Engine",
   description: "Search the web for information",
@@ -91,26 +350,23 @@ const searchTool: Tool<unknown, SearchData, [], string> = {
     },
     required: ["query"],
   },
-  handler: async ({ query, limit = 10 }) => {
+  handler: async ({ context, data }, args) => {
+    const { query, limit = 10 } = args;
     const results = await searchAPI.query(query, limit);
     return {
       data: `Found ${results.length} results for "${query}"`,
       contextUpdate: { searchResults: results },
     };
   },
-};
+});
 ```
 
-## Tool Execution Context
-
-Tools receive execution context including:
+## Simplified Tool Context
 
-- **Current context** - Agent and route context
-- **Session data** - Collected conversation data
-- **Route information** - Current route and step details
+Tools receive a simplified context with direct access to agent data and helper methods:
 
 ```typescript
-const userProfileTool: Tool<unknown, UserData, [], string> = {
+agent.addTool({
   id: "get_user_profile",
   description: "Retrieve user profile information",
   parameters: {
@@ -122,20 +378,43 @@ const userProfileTool: Tool<unknown, UserData, [], string> = {
       },
     },
   },
-  handler: async (toolContext, args) => {
-    // Access current context
-    const currentUserId = toolContext.context.userId || args.userId;
-
-    // Access collected data
-    const preferences = toolContext.data.userPreferences;
+  handler: async ({ context, data, updateContext, updateData }, args) => {
+    // Direct access to current context and data
+    const currentUserId = context.userId || args.userId;
+    const preferences = data.userPreferences;
 
     const profile = await userAPI.getProfile(currentUserId);
+    
+    // Use helper methods for updates
+    await updateData({ userProfile: profile });
+    
     return {
       data: `Retrieved profile for ${profile.name}`,
-      dataUpdate: { userProfile: profile },
     };
   },
-};
+});
+```
+
+### Context Helper Methods
+
+The simplified context provides convenient helper methods:
+
+```typescript
+agent.addTool({
+  id: "user_preferences",
+  handler: async ({ context, data, getField, setField, hasField }) => {
+    // Check if field exists
+    if (hasField('preferences')) {
+      const prefs = getField('preferences');
+      console.log('Current preferences:', prefs);
+    }
+    
+    // Set field value
+    await setField('lastLogin', new Date().toISOString());
+    
+    return { data: "Preferences updated" };
+  },
+});
 ```
 
 ## Tool Response Format
@@ -253,17 +532,30 @@ const apiTool: Tool<unknown, ApiData, [], string> = {
 
 ## Tool Scoping
 
-Tools can be registered at different levels:
+Tools can be added at different scopes using the new ToolManager API:
 
 ### Agent-Level Tools
 
 Available to all routes and steps:
 
 ```typescript
-const agent = new Agent({
-  name: "Assistant",
-  provider: openaiProvider,
-  tools: [globalSearchTool, userManagementTool],
+// Add tools directly to agent scope
+agent.addTool({
+  id: "global_search",
+  description: "Search across all data sources",
+  handler: async ({ context, data }) => {
+    // Tool logic here
+    return { data: "Search completed" };
+  },
+});
+
+// Or register for later use
+agent.tool.register({
+  id: "user_management",
+  description: "Manage user accounts",
+  handler: async ({ context, data }) => {
+    return { data: "User managed" };
+  },
 });
 ```
 
@@ -274,7 +566,15 @@ Available only within specific routes:
 ```typescript
 const supportRoute = agent.createRoute({
   title: "Customer Support",
-  tools: [ticketCreationTool, knowledgeBaseTool],
+});
+
+// Add tools to route scope
+supportRoute.addTool({
+  id: "create_ticket",
+  description: "Create support ticket",
+  handler: async ({ context, data }) => {
+    return { data: "Ticket created" };
+  },
 });
 ```
 
@@ -283,10 +583,22 @@ const supportRoute = agent.createRoute({
 Available only in specific steps:
 
 ```typescript
+// Add tool directly to step
 const bookingStep = route.initialStep.nextStep({
   prompt: "Ready to book?",
-  tools: [paymentProcessingTool],
   requires: ["bookingDetails"],
+}).addTool({
+  id: "process_payment",
+  description: "Process payment for booking",
+  handler: async ({ context, data }) => {
+    return { data: "Payment processed" };
+  },
+});
+
+// Or reference registered tools by ID
+const step = route.initialStep.nextStep({
+  prompt: "Processing...",
+  tools: ['registered_tool_id'], // Reference by ID
 });
 ```
 
@@ -335,12 +647,324 @@ Tools are validated at registration time:
 - **Type checking** - TypeScript types must match schemas
 - **Name uniqueness** - Tool names must be unique within scope
 
+## Pattern Helpers
+
+ToolManager provides built-in helpers for common tool patterns:
+
+### Data Enrichment Tools
+
+For tools that modify collected data:
+
+```typescript
+const enrichmentTool = agent.tool.createDataEnrichment({
+  id: "enrich_user_data",
+  fields: ['name', 'email'],
+  enricher: async (context, data) => ({
+    fullName: `${data.name} (${context.userRole})`,
+    emailDomain: data.email.split('@')[1]
+  })
+});
+
+// Register or add to scope
+agent.tool.register(enrichmentTool);
+```
+
+### Validation Tools
+
+For tools that validate data fields:
+
+```typescript
+const validationTool = agent.tool.createValidation({
+  id: "validate_booking",
+  fields: ['bookingDate', 'guestCount'],
+  validator: async (context, data) => {
+    const errors = [];
+    if (!data.bookingDate) errors.push({ field: 'bookingDate', message: 'Required' });
+    if (data.guestCount < 1) errors.push({ field: 'guestCount', message: 'Must be positive' });
+    
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+});
+
+agent.addTool(validationTool);
+```
+
+### API Call Tools
+
+For tools that make external API calls:
+
+```typescript
+const apiTool = agent.tool.createApiCall({
+  id: "fetch_weather",
+  endpoint: "https://api.weather.com/forecast",
+  method: "GET",
+  headers: { "API-Key": process.env.WEATHER_API_KEY },
+  transform: (response) => response.data.forecast
+});
+
+agent.tool.register(apiTool);
+```
+
+### Computation Tools
+
+For tools that perform calculations:
+
+```typescript
+const computeTool = agent.tool.createComputation({
+  id: "calculate_total",
+  inputs: ['price', 'quantity', 'taxRate'],
+  compute: async (context, inputs) => {
+    const subtotal = inputs.price * inputs.quantity;
+    const tax = subtotal * inputs.taxRate;
+    return subtotal + tax;
+  }
+});
+
+agent.addTool(computeTool);
+```
+
+## Tool Registry and Resolution
+
+### Registry Management
+
+```typescript
+// Register multiple tools at once
+agent.tool.registerMany([
+  { id: 'tool1', handler: () => {} },
+  { id: 'tool2', handler: () => {} },
+  existingToolInstance
+]);
+
+// Check if tool is registered
+if (agent.tool.isRegistered('my_tool')) {
+  console.log('Tool is available');
+}
+
+// Get all registered tools
+const registeredTools = agent.tool.getRegistered();
+```
+
+### Tool Resolution
+
+Tools are resolved with the following priority:
+
+1. **Step-level inline tools** (highest priority)
+2. **Step-level tool references** (by ID) → Registry lookup
+3. **Route-level tools**
+4. **Agent-level tools**
+5. **Registered tools** (fallback for unresolved IDs)
+
+```typescript
+// Find tool across all scopes
+const tool = agent.tool.find('my_tool');
+
+// Get available tools for current context
+const availableTools = agent.tool.getAvailable();
+```
+
+## Tools as Step Lifecycle Hooks
+
+Tools can be used as `prepare` and `finalize` functions in step lifecycle, enabling powerful data processing and side effects before and after AI responses:
+
+### Using Tools for Step Preparation
+
+```typescript
+// Create a preparation tool
+agent.addTool({
+  id: "validate_user_data",
+  name: "User Data Validator",
+  description: "Validate user data before processing",
+  parameters: { type: "object", properties: {} },
+  handler: async ({ context, data, updateData }) => {
+    // Validation logic with helper methods
+    if (!data.email?.includes("@")) {
+      throw new Error("Invalid email address");
+    }
+    
+    // Mark as validated using helper method
+    await updateData({ emailValidated: true });
+    
+    return "User validation completed successfully";
+  },
+});
+
+// Use tool as prepare hook
+const step = route.initialStep.nextStep({
+  id: "collect_info",
+  description: "Collect user information",
+  collect: ["name", "email"],
+  prompt: "Please provide your name and email.",
+  prepare: "validate_user_data", // Tool ID string - executes before AI response
+});
+```
+
+### Using Tools for Step Finalization
+
+```typescript
+// Create a finalization tool with ToolResult pattern
+agent.addTool({
+  id: "send_welcome_email",
+  name: "Welcome Email Sender",
+  description: "Send welcome email after data collection",
+  parameters: { type: "object", properties: {} },
+  handler: async ({ context, data }) => {
+    const emailResult = await emailService.sendWelcome(data.email, data.name);
+    
+    return {
+      data: `Welcome email sent to ${data.email}`,
+      success: emailResult.success,
+      contextUpdate: { 
+        lastEmailSent: new Date().toISOString(),
+        emailsSent: (context.emailsSent || 0) + 1
+      }
+    };
+  },
+});
+
+// Use tool as finalize hook
+const welcomeStep = route.initialStep.nextStep({
+  id: "send_welcome",
+  description: "Send welcome email",
+  prompt: "Welcome! Check your email for confirmation.",
+  finalize: "send_welcome_email", // Tool ID string - executes after AI response
+});
+```
+
+### Multiple Lifecycle Approaches
+
+Tools can be used in step lifecycle in several ways:
+
+```typescript
+// Method 1: Tool ID reference (most common)
+const step1 = route.initialStep.nextStep({
+  prompt: "Processing your request...",
+  prepare: "setup_processing", // References registered tool by ID
+  finalize: "cleanup_processing", // References registered tool by ID
+});
+
+// Method 2: Inline tool definition
+const step2 = route.initialStep.nextStep({
+  prompt: "Validating your information...",
+  prepare: {
+    id: "inline_validator",
+    description: "Validate data inline",
+    handler: async ({ context, data }) => {
+      // Inline validation logic
+      return data.isValid ? "Validation passed" : "Validation failed";
+    }
+  }
+});
+
+// Method 3: Function reference (traditional approach)
+const step3 = route.initialStep.nextStep({
+  prompt: "Setting up your account...",
+  prepare: async (context, data) => {
+    // Traditional function approach
+    console.log("Preparing account setup...");
+  },
+  finalize: async (context, data) => {
+    // Traditional function approach
+    console.log("Account setup complete");
+  }
+});
+```
+
+### Advanced Lifecycle Tool Patterns
+
+```typescript
+// Data enrichment during preparation
+agent.addTool({
+  id: "enrich_user_context",
+  description: "Enrich user context before processing",
+  handler: async ({ context, data, updateContext, updateData }) => {
+    // Fetch additional user data
+    const userProfile = await userService.getProfile(context.userId);
+    const preferences = await userService.getPreferences(context.userId);
+    
+    // Update context with enriched data
+    await updateContext({
+      userProfile,
+      preferences,
+      lastEnrichment: new Date().toISOString()
+    });
+    
+    // Update collected data
+    await updateData({
+      userTier: userProfile.tier,
+      preferredLanguage: preferences.language
+    });
+    
+    return {
+      data: "User context enriched successfully",
+      contextUpdate: { enrichmentComplete: true }
+    };
+  }
+});
+
+// Audit logging during finalization
+agent.addTool({
+  id: "audit_step_completion",
+  description: "Log step completion for audit trail",
+  handler: async ({ context, data }) => {
+    await auditService.logStepCompletion({
+      userId: context.userId,
+      stepId: context.currentStep,
+      timestamp: new Date(),
+      collectedData: data
+    });
+    
+    return "Step completion logged";
+  }
+});
+
+// Use in step with both prepare and finalize
+const auditedStep = route.initialStep.nextStep({
+  prompt: "Processing your secure transaction...",
+  prepare: "enrich_user_context",
+  finalize: "audit_step_completion",
+  collect: ["transactionAmount", "recipientAccount"]
+});
+```
+
+### Benefits of Tool-Based Lifecycle Hooks
+
+- ✅ **Reusable Logic** - Tools can be shared across steps and routes
+- ✅ **Error Handling** - Tool execution includes automatic error handling
+- ✅ **Context Access** - Tools receive full context and collected data
+- ✅ **Data Updates** - Tools can modify collected data or agent context
+- ✅ **Flexible Returns** - Support both simple returns and complex ToolResult objects
+- ✅ **Type Safety** - Full TypeScript support with automatic inference
+- ✅ **Registry Integration** - Reference tools by ID for consistency
+
+### Lifecycle Execution Order
+
+When using tools in step lifecycle:
+
+1. **Prepare Phase**: Tool executes before AI response generation
+2. **AI Response**: Agent generates response based on enriched context/data
+3. **Finalize Phase**: Tool executes after AI response, can process results
+
+```typescript
+const lifecycleStep = route.initialStep.nextStep({
+  prompt: "Let me process your request...",
+  prepare: "setup_processing", // 1. Executes first
+  // 2. AI generates response using enriched context
+  finalize: "complete_processing", // 3. Executes last
+});
+```
+
 ## Best Practices
 
+- **Use pattern helpers** - Leverage built-in helpers for common patterns
+- **Register reusable tools** - Use registry for tools referenced across multiple steps
 - **Keep tools focused** - Each tool should do one thing well
 - **Use descriptive names** - Tool names should be clear and specific
 - **Handle errors gracefully** - Provide meaningful error messages
-- **Leverage context updates** - Use context to maintain conversation state
+- **Leverage helper methods** - Use `updateContext`, `updateData`, `getField`, etc.
 - **Validate parameters** - Use JSON Schema constraints effectively
 - **Consider performance** - Avoid long-running operations when possible
 - **Document thoroughly** - Provide clear descriptions for AI usage
+- **Use lifecycle hooks** - Leverage prepare/finalize for setup and cleanup logic