elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/10-CLIENT-TOOLS.md

@@ -0,0 +1,665 @@
+# 10. Client Tools System
+
+> Generalized, channel-agnostic tool execution for AI agent interactions.
+> Last updated: 2026-04-02
+
+---
+
+## Problem: Current State
+
+Tools are currently **duplicated and tightly coupled** to ElevenLabs:
+
+| Location | Channel | Tools | Format |
+|----------|---------|-------|--------|
+| `whatsapp-agent.service.ts` (1000+ lines) | WhatsApp chat (ElevenLabs WS) | 10 tools | Inline in WS message handler |
+| `elevenlabs-tool.service.ts` | Voice calls (ElevenLabs HTTP webhook) | 7 tools | HTTP request/response |
+
+**Why this is a problem:**
+
+- Same tools implemented twice (e.g., `check_availability` exists in both files).
+- Business logic is mixed with protocol handling (WS framing, HTTP response format).
+- Adding a new tool requires changes in 2+ places.
+- Impossible to use tools from a different AI provider (e.g., OpenAI function calling).
+- No way to configure which tools are available per tenant or agent.
+- No tool execution logging or analytics.
+
+---
+
+## Architecture: Three Layers
+
+The target system separates concerns into three layers. Each layer has a single responsibility and zero knowledge of the layers above it.
+
+```
++--------------------------------------------------------------+
+|                     CALLER (AI Provider)                      |
+|                                                               |
+|  ElevenLabs WS    ElevenLabs HTTP    OpenAI Functions    ... |
+|  (WhatsApp chat)  (Voice call)       (Future)                |
++-------+----------------+------------------+------------------+
+        |                |                  |
+        v                v                  v
++--------------------------------------------------------------+
+|                    ADAPTER LAYER                              |
+|                                                               |
+|  ElevenLabsWsAdapter  ElevenLabsHttpAdapter  OpenAIAdapter   |
+|  - Parse WS message   - Parse HTTP body       - Parse FC     |
+|  - Extract tool call  - Extract tool call     - Extract FC   |
+|  - Format result      - Format response       - Format resp  |
++-------+------------------------------------------------------+
+        |
+        v  Standardized ToolCall + ToolContext
++--------------------------------------------------------------+
+|                    TOOL REGISTRY                              |
+|                                                               |
+|  ToolRegistryService                                          |
+|  - Discovers all @Tool() decorated handlers                   |
+|  - Validates parameters against schema                        |
+|  - Resolves tool by name                                      |
+|  - Checks tenant permissions / feature flags                  |
+|  - Executes tool handler                                      |
+|  - Logs execution (ToolExecutionLog)                          |
++-------+------------------------------------------------------+
+        |
+        v
++--------------------------------------------------------------+
+|                    TOOL HANDLERS                              |
+|                                                               |
+|  @Tool('check_availability')    -> AppointmentService         |
+|  @Tool('reserve_slot')          -> AppointmentService         |
+|  @Tool('list_reservations')     -> AppointmentService         |
+|  @Tool('cancel_reservation')    -> AppointmentService         |
+|  @Tool('reschedule_reservation')-> AppointmentService         |
+|  @Tool('check_patient_history') -> PatientService             |
+|  @Tool('forward_to_operator')   -> OperatorService            |
+|  @Tool('forward_conversation')  -> OperatorService            |
+|  @Tool('send_example_photo')    -> MediaService + MinIO       |
+|  @Tool('call_patient')          -> ElevenLabsService          |
+|  @Tool('confirm_appointment_validation') -> ValidationService |
+|  @Tool('request_payment')       -> TekTipPayService (stub)    |
+|  @Tool('send_sms')              -> NetGsmService (stub)       |
+|                                                               |
+|  Each handler: receives ToolContext + params -> returns result |
+|  Pure business logic -- zero knowledge of AI provider format  |
++--------------------------------------------------------------+
+```
+
+---
+
+## Core Interfaces
+
+### ToolContext (Channel-Agnostic)
+
+Every tool handler receives a `ToolContext` that identifies who is calling, which tenant, which channel, and all channel-specific metadata. The handler never needs to know whether the call came from a WebSocket message or an HTTP webhook.
+
+```typescript
+interface ToolContext {
+  // Who
+  tenantId: string;
+  tenant: TenantWithSettings;      // Full tenant with parsed settings
+  clinicId: string | null;         // Which clinic this interaction belongs to
+  clinic: ClinicWithSettings | null;
+
+  // Patient / contact
+  patientPhone: string;            // E.164 format
+  patientName: string;
+
+  // Channel info
+  channel: 'whatsapp' | 'voice_call' | 'instagram' | 'test_chat';
+  channelMetadata: {
+    chatId?: string;               // WhatsApp chat ID
+    sessionId?: string;            // WhatsApp session ID
+    conversationId?: string;       // ElevenLabs conversation ID
+    agentId?: string;              // ElevenLabs agent ID
+    phoneNumberId?: string;        // Which PhoneNumber received this interaction
+    patientId?: string;            // Resolved Patient ID (looked up on tool execution by phone match)
+  };
+}
+```
+
+### ToolDefinition
+
+Describes a tool for discovery, validation, and AI prompt generation.
+
+```typescript
+interface ToolDefinition {
+  name: string;                    // e.g., 'check_availability'
+  description: string;             // For AI agent prompt
+  parameters: JsonSchema;          // JSON Schema for parameter validation
+  requiredFeatures?: string[];     // Tenant feature flags needed (e.g., ['google_calendar'])
+  channels?: string[];             // Which channels support this tool (default: all)
+}
+```
+
+### ToolResult
+
+Every tool handler returns a `ToolResult`. Adapters translate this into the provider-specific format.
+
+```typescript
+interface ToolResult {
+  data: any;                       // Tool-specific result payload
+  isError: boolean;                // Whether this is an error result
+}
+```
+
+---
+
+## @Tool() Decorator and Auto-Discovery
+
+### The Decorator
+
+The `@Tool()` decorator attaches a `ToolDefinition` to a method via NestJS `SetMetadata`. No registration boilerplate is needed -- the registry finds everything automatically.
+
+```typescript
+import { SetMetadata } from '@nestjs/common';
+
+export const TOOL_METADATA_KEY = 'tool:definition';
+
+export function Tool(definition: ToolDefinition): MethodDecorator {
+  return SetMetadata(TOOL_METADATA_KEY, definition);
+}
+```
+
+### Auto-Discovery via DiscoveryService
+
+On module initialization, `ToolRegistryService` uses NestJS `DiscoveryService` to scan every provider in the application. For each provider instance, it iterates over all methods and checks for the `TOOL_METADATA_KEY` metadata. Any decorated method is registered in the internal `tools` map.
+
+```typescript
+@Injectable()
+export class ToolRegistryService implements OnModuleInit {
+  private tools = new Map<string, {
+    instance: any;
+    method: string;
+    definition: ToolDefinition;
+  }>();
+
+  constructor(
+    private readonly discoveryService: DiscoveryService,
+    private readonly reflector: Reflector,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  onModuleInit() {
+    const providers = this.discoveryService.getProviders();
+    for (const wrapper of providers) {
+      const instance = wrapper.instance;
+      if (!instance) continue;
+
+      const methods = Object.getOwnPropertyNames(Object.getPrototypeOf(instance));
+      for (const method of methods) {
+        const definition = this.reflector.get<ToolDefinition>(
+          TOOL_METADATA_KEY,
+          instance[method],
+        );
+        if (definition) {
+          this.tools.set(definition.name, { instance, method, definition });
+        }
+      }
+    }
+  }
+}
+```
+
+This means adding a new tool is a single-step process: write a method with `@Tool()` in any `@Injectable()` class, and the registry picks it up on next startup.
+
+### Usage in a Handler Class
+
+```typescript
+@Injectable()
+export class CalendarTools {
+  constructor(
+    private readonly appointmentService: AppointmentService,
+    private readonly prisma: PrismaService,
+    private readonly eventEmitter: EventEmitter2,
+  ) {}
+
+  @Tool({
+    name: 'check_availability',
+    description: 'Check available appointment slots for a given date',
+    parameters: {
+      type: 'object',
+      properties: {
+        date: { type: 'string', description: 'Date in YYYY-MM-DD format' },
+      },
+      required: ['date'],
+    },
+    requiredFeatures: ['appointments'],
+  })
+  async checkAvailability(ctx: ToolContext, params: { date: string }): Promise<ToolResult> {
+    const today = new Date().toISOString().split('T')[0];
+    if (params.date < today) {
+      return {
+        data: { error: `Past date. Today is: ${today}` },
+        isError: true,
+      };
+    }
+
+    const result = await this.appointmentService.checkAvailability(ctx.clinicId, params.date);
+    return { data: result, isError: false };
+  }
+}
+```
+
+---
+
+## Tool Registry Service
+
+The registry is the central coordinator. It handles discovery (described above), tool lookup by name, feature flag enforcement, execution, error handling, and logging.
+
+### getAvailableTools()
+
+Returns all tools that a given tenant can use on a given channel. Used by adapters to generate tool schemas for AI providers.
+
+```typescript
+getAvailableTools(tenant: TenantWithSettings, channel: string): ToolDefinition[] {
+  return Array.from(this.tools.values())
+    .filter(({ definition }) => {
+      if (definition.channels && !definition.channels.includes(channel)) return false;
+      if (definition.requiredFeatures) {
+        return definition.requiredFeatures.every(f => tenant.enabledFeatures.includes(f));
+      }
+      return true;
+    })
+    .map(({ definition }) => definition);
+}
+```
+
+### execute()
+
+Resolves a tool by name, checks feature flags, runs the handler, catches errors, and logs the result.
+
+```typescript
+async execute(
+  toolName: string,
+  ctx: ToolContext,
+  params: Record<string, any>,
+): Promise<ToolResult> {
+  const tool = this.tools.get(toolName);
+  if (!tool) {
+    return { data: { error: `Unknown tool: ${toolName}` }, isError: true };
+  }
+
+  // Feature flag check
+  if (tool.definition.requiredFeatures) {
+    const missing = tool.definition.requiredFeatures.find(
+      f => !ctx.tenant.enabledFeatures.includes(f),
+    );
+    if (missing) {
+      return { data: { error: `Feature not enabled: ${missing}` }, isError: true };
+    }
+  }
+
+  // TODO: Validate params against definition.parameters (JSON Schema)
+
+  const startTime = Date.now();
+  try {
+    const result = await tool.instance[tool.method](ctx, params);
+    this.logExecution(toolName, ctx, params, result, Date.now() - startTime);
+    return result;
+  } catch (error) {
+    const errorResult = { data: { error: error.message }, isError: true };
+    this.logExecution(toolName, ctx, params, errorResult, Date.now() - startTime);
+    return errorResult;
+  }
+}
+```
+
+---
+
+## Adapters
+
+Adapters translate between a provider-specific protocol and the generic `ToolContext` + `ToolResult` format. Each adapter is an `@Injectable()` class that depends on `ToolRegistryService`.
+
+### ElevenLabsWsAdapter (WhatsApp Chat)
+
+Handles WebSocket `client_tool_call` messages from ElevenLabs during WhatsApp AI conversations.
+
+```typescript
+@Injectable()
+export class ElevenLabsWsToolAdapter {
+  constructor(private readonly toolRegistry: ToolRegistryService) {}
+
+  async handleToolCall(
+    wsMessage: ElevenLabsWsToolCallMessage,
+    ctx: ToolContext,
+  ): Promise<ElevenLabsWsToolResultMessage> {
+    const { tool_call_id, tool_name, parameters } = wsMessage;
+
+    const result = await this.toolRegistry.execute(tool_name, ctx, parameters);
+
+    return {
+      type: 'client_tool_result',        // MUST be lowercase
+      tool_call_id,
+      result: JSON.stringify(result.data),
+      is_error: result.isError,           // REQUIRED field -- omitting causes WS 1008 disconnect
+    };
+  }
+}
+```
+
+**Flow:** Patient message (via Meta Business API webhook) -> ElevenLabs WS -> `client_tool_call` -> `WhatsAppAgentService.handleToolCall()` -> `ElevenLabsWsAdapter.handleToolCall()` -> `ToolRegistryService.execute()` -> handler -> adapter formats `client_tool_result` -> WS sends to ElevenLabs -> AI continues. Tools that send messages (e.g., `forward_to_operator`, `send_example_photo`) use `MetaWhatsAppService` directly.
+
+### ElevenLabsHttpAdapter (Voice Calls)
+
+Handles HTTP webhook POST requests from ElevenLabs during SIP trunk voice calls.
+
+```typescript
+@Injectable()
+export class ElevenLabsHttpToolAdapter {
+  constructor(private readonly toolRegistry: ToolRegistryService) {}
+
+  async handleToolCall(
+    toolName: string,
+    body: ElevenLabsToolWebhookBody,
+    ctx: ToolContext,
+  ): Promise<any> {
+    const result = await this.toolRegistry.execute(toolName, ctx, body.parameters || body);
+    return result.data;  // HTTP response body (JSON)
+  }
+}
+```
+
+**Flow:** Voice call -> AI needs data -> ElevenLabs calls `POST /webhooks/elevenlabs/tools/:toolName` -> `ElevenLabsToolController` resolves tenant from `agent_id` -> `ElevenLabsHttpAdapter.handleToolCall()` -> `ToolRegistryService.execute()` -> handler -> return JSON response.
+
+### OpenAIFunctionAdapter (Future)
+
+Converts tool definitions to OpenAI function calling schemas and handles function call results. This adapter enables switching AI providers without touching any tool handler.
+
+```typescript
+@Injectable()
+export class OpenAIFunctionAdapter {
+  constructor(private readonly toolRegistry: ToolRegistryService) {}
+
+  getToolSchemas(tenant: TenantWithSettings, channel: string) {
+    return this.toolRegistry.getAvailableTools(tenant, channel).map(def => ({
+      type: 'function' as const,
+      function: {
+        name: def.name,
+        description: def.description,
+        parameters: def.parameters,
+      },
+    }));
+  }
+
+  async handleFunctionCall(
+    functionCall: { name: string; arguments: string },
+    ctx: ToolContext,
+  ) {
+    const params = JSON.parse(functionCall.arguments);
+    const result = await this.toolRegistry.execute(functionCall.name, ctx, params);
+    return JSON.stringify(result.data);
+  }
+}
+```
+
+---
+
+## Complete Tool Inventory (13 Tools)
+
+### 1. check_availability
+
+- **Parameters:** `{ date: string }` (YYYY-MM-DD)
+- **Required features:** `appointments`
+- **Channels:** all
+- **What it does:** Queries the local appointment database for the given date. Returns available time slots based on clinic working hours, blocked dates, and existing appointments. Our calendar is the source of truth; Google Calendar is optional sync.
+- **Result:** `{ available_slots: [{ start, end }], date, timezone }`
+
+### 2. reserve_slot
+
+- **Parameters:** `{ patient_name?: string, iso_start: string, iso_end: string, notes?: string }`
+- **Required features:** `appointments`
+- **Channels:** all
+- **What it does:** Re-checks availability for race protection, creates an appointment in the local database. If Google Calendar sync is enabled for the clinic, the event is also pushed to Google Calendar. Emits `appointment.created` event.
+- **Result:** `{ appointment_id, start, end, patient_name }`
+
+### 3. list_reservations
+
+- **Parameters:** none
+- **Required features:** `appointments`
+- **Channels:** all
+- **What it does:** Lists the current patient's upcoming appointments from the local database, filtered by `patient_id` (resolved from `patientPhone`).
+- **Result:** `{ reservations: [{ appointment_id, start, end, summary }] }`
+
+### 4. cancel_reservation
+
+- **Parameters:** `{ appointment_id: string }`
+- **Required features:** `appointments`
+- **Channels:** all
+- **What it does:** Verifies patient ownership before cancelling. Updates status to `cancelled` in local DB. Syncs to Google Calendar if connected. Emits `appointment.cancelled` event.
+- **Result:** `{ cancelled: true, appointment_id }`
+
+### 5. reschedule_reservation
+
+- **Parameters:** `{ old_appointment_id: string, new_iso_start: string, new_iso_end: string, notes?: string }`
+- **Required features:** `appointments`
+- **Channels:** all
+- **What it does:** Cancels the old appointment and creates a new one. Re-checks availability for the new slot. Syncs both changes to Google Calendar if connected. Emits `appointment.rescheduled` event.
+- **Result:** `{ old_appointment_id, new_appointment_id, new_start, new_end }`
+
+### 6. check_patient_history
+
+- **Parameters:** none
+- **Required features:** none
+- **Channels:** all
+- **What it does:** Queries the `Patient` model (replacing the old `WhatsAppContactProfile`) by phone match. Returns the patient's full profile, medical history, treatment plans, past appointments, examination records, and session summaries. The `patientId` is resolved on tool execution and stored in `channelMetadata.patientId`.
+- **Result:** `{ patient, medical_history, treatment_plans, appointments, examination_records, sessions }`
+
+### 7. forward_to_operator
+
+- **Parameters:** `{ message?: string }`
+- **Required features:** `operator_workflow`
+- **Channels:** whatsapp, instagram
+- **What it does:** Finds all media messages in the current session, forwards each to the operator (doctor) phone number via Meta Business API with 500ms delay between sends. Creates an `OperatorRequest` with a unique REF code. Sets `awaiting_operator` flag on the session.
+- **Result:** `{ ref_code, forwarded_count, failed_count }`
+
+### 8. forward_conversation_to_operator
+
+- **Parameters:** `{ summary?: string, patient_messages?: string }`
+- **Required features:** `conversation_forwarding`
+- **Channels:** whatsapp, instagram
+- **What it does:** Forwards conversation text (not media) to the operator. Useful when the doctor needs conversation context rather than photos.
+- **Result:** `{ forwarded: true }`
+
+### 9. send_example_photo
+
+- **Parameters:** none
+- **Required features:** `operator_workflow`
+- **Channels:** whatsapp, instagram
+- **What it does:** Sends a pre-configured guide image (from MinIO) to the patient via Meta Business API send media endpoint, showing camera angle and posing instructions. Uses the tenant's `operator_example_photo_caption`.
+- **Result:** `{ sent: true }`
+
+### 10. call_patient
+
+- **Parameters:** `{ reason?: string }`
+- **Required features:** none
+- **Channels:** whatsapp
+- **What it does:** Initiates an outbound voice call to the patient via ElevenLabs SIP trunk. Passes the reason as context to the voice agent.
+- **Result:** `{ call_initiated: true, conversation_id }`
+
+### 11. confirm_appointment_validation
+
+- **Parameters:** `{ result: 'confirmed' | 'cancelled' | 'reschedule', reschedule_request?: string, patient_message?: string }`
+- **Required features:** `appointment_validation`
+- **Channels:** voice_call
+- **What it does:** Records the outcome of a validation call. Updates the `AppointmentValidationEntry` status. If rescheduled, stores the patient's preferred time.
+- **Result:** `{ recorded: true, result }`
+
+### 12. request_payment (stub)
+
+- **Parameters:** `{ amount: number, description?: string, appointment_id?: string }`
+- **Required features:** `payments`
+- **Channels:** whatsapp, voice_call
+- **What it does:** Creates a payment link via TekTipPay and sends it to the patient (via WhatsApp message or SMS for voice calls). **Stub:** TekTipPay is an empty placeholder module -- handler is registered but returns a "not yet available" error until the integration is implemented.
+- **Result:** `{ payment_link, payment_id, amount }`
+
+### 13. send_sms (stub)
+
+- **Parameters:** `{ phone?: string, message: string }`
+- **Required features:** `sms_notifications`
+- **Channels:** whatsapp, voice_call
+- **What it does:** Sends an SMS to the patient (or a custom number if provided) via NetGSM. **Stub:** NetGSM is an empty placeholder module -- handler is registered but returns a "not yet available" error until the integration is implemented.
+- **Result:** `{ sent: true, job_id }`
+
+---
+
+## Tool Execution Logging
+
+Every tool invocation is logged to the `tool_execution_logs` table for analytics, debugging, and usage tracking.
+
+### Prisma Model
+
+```prisma
+model ToolExecutionLog {
+  id              String   @id @default(uuid())
+  tenantId        String
+  toolName        String
+  channel         String   // 'whatsapp', 'voice_call', 'instagram', 'test_chat'
+  patientPhone    String   @default("")
+  conversationId  String?
+  parameters      Json     @default("{}")
+  result          Json     @default("{}")
+  isError         Boolean  @default(false)
+  durationMs      Int      @default(0)
+  createdAt       DateTime @default(now())
+
+  @@index([tenantId, createdAt(sort: Desc)])
+  @@index([toolName, createdAt(sort: Desc)])
+  @@index([conversationId])
+  @@map("tool_execution_logs")
+}
+```
+
+### Write Behavior
+
+Logs are written fire-and-forget after each tool execution. A failed log write never causes the tool result to fail.
+
+```typescript
+private async logExecution(
+  toolName: string, ctx: ToolContext, params: any, result: ToolResult, durationMs: number,
+) {
+  await this.prisma.toolExecutionLog.create({
+    data: {
+      tenantId: ctx.tenantId,
+      toolName,
+      channel: ctx.channel,
+      patientPhone: ctx.patientPhone,
+      conversationId: ctx.channelMetadata.conversationId,
+      parameters: params,
+      result: result.data,
+      isError: result.isError,
+      durationMs,
+    },
+  }).catch(() => {}); // fire-and-forget
+}
+```
+
+### Cleanup
+
+BullMQ repeatable job deletes logs older than 30 days (or per-tenant `log_retention_days` setting).
+
+---
+
+## Per-Tenant Tool Configuration (Future)
+
+The system supports future per-tenant tool customization via tenant settings:
+
+```typescript
+// In TenantSettings:
+tools: {
+  disabled_tools: string[];           // e.g., ['call_patient'] -- disable specific tools
+  tool_overrides: Record<string, {    // Per-tool config overrides
+    custom_prompt?: string;           // Override tool description sent to AI
+    parameters_override?: JsonSchema; // Override parameter schema
+  }>;
+};
+```
+
+This allows tenants to:
+
+- **Disable tools** they do not need, reducing AI confusion.
+- **Customize tool descriptions** for their specific AI agent prompt.
+- **Add parameter constraints** (e.g., limit booking to specific time ranges).
+
+The registry checks `disabled_tools` during `getAvailableTools()` and merges `tool_overrides` into the definition before returning to adapters.
+
+---
+
+## File Structure
+
+```
+src/tools/
+  tools.module.ts                    # ToolsModule -- imports all handler classes
+  tool.decorator.ts                  # @Tool() decorator
+  tool.interfaces.ts                 # ToolContext, ToolDefinition, ToolResult, ToolHandler
+  tool-registry.service.ts           # Discovery, validation, execution, logging
+  adapters/
+    elevenlabs-ws.adapter.ts         # WS client_tool_call <-> ToolRegistry
+    elevenlabs-http.adapter.ts       # HTTP webhook <-> ToolRegistry
+    openai-function.adapter.ts       # OpenAI function calling <-> ToolRegistry (future)
+  handlers/
+    calendar.tools.ts                # check_availability, reserve_slot, list, cancel, reschedule
+    operator.tools.ts                # forward_to_operator, forward_conversation, send_example_photo
+    patient.tools.ts                 # check_patient_history, call_patient
+    validation.tools.ts              # confirm_appointment_validation
+    payment.tools.ts                 # request_payment (stub -- TekTipPay not yet implemented)
+    notification.tools.ts            # send_sms (stub -- NetGSM not yet implemented)
+  schemas/                           # JSON Schema definitions for each tool (optional, can be inline)
+```
+
+---
+
+## Integration Flows
+
+### WhatsApp Chat (ElevenLabs WebSocket)
+
+```
+Patient message
+  -> ElevenLabs WS
+  -> agent_response / client_tool_call
+  -> WhatsAppAgentService.handleToolCall()
+  -> ElevenLabsWsAdapter.handleToolCall()
+  -> ToolRegistryService.execute(toolName, ctx, params)
+  -> CalendarTools.reserveSlot(ctx, params)
+  -> ElevenLabsWsAdapter formats -> client_tool_result
+  -> WS sends result
+  -> AI continues conversation
+```
+
+### Voice Call (ElevenLabs HTTP Webhook)
+
+```
+Voice call
+  -> AI needs data
+  -> ElevenLabs calls POST /webhooks/elevenlabs/tools/:toolName
+  -> ElevenLabsToolController.handleTool()
+  -> Resolve ToolContext (tenant from agent_id header)
+  -> ElevenLabsHttpAdapter.handleToolCall()
+  -> ToolRegistryService.execute(toolName, ctx, params)
+  -> CalendarTools.reserveSlot(ctx, params)
+  -> Return JSON response to ElevenLabs
+```
+
+### Test Chat (Admin Panel)
+
+```
+Admin sends test message
+  -> TestChatService
+  -> AI response / tool_call
+  -> Same ToolRegistry.execute() -- channel = 'test_chat'
+  -> Tool executes (or mocks based on flag)
+```
+
+---
+
+## Benefits
+
+| Benefit | How |
+|---------|-----|
+| **Zero duplication** | Each tool implemented once, used from any channel |
+| **AI provider agnostic** | Adapters handle protocol differences; handlers never know about ElevenLabs/OpenAI |
+| **Easy to add tools** | Write a handler method with `@Tool()` -- auto-discovered on startup |
+| **Easy to add providers** | Write a new adapter -- all existing tools work immediately |
+| **Feature-flag gated** | `requiredFeatures` on each tool, checked at registry level |
+| **Channel-aware** | `channels` field limits which channels can use which tools |
+| **Observable** | `ToolExecutionLog` tracks every invocation with timing and error state |
+| **Testable** | Tool handlers are pure business logic -- inject mocks, test independently |
+| **Per-tenant configurable** | Disable/customize tools per tenant (future) |