​

Voice Tool Dispatcher

​

Overview

​

Request contract

POST /api/incoming-call-webhook-tool/skills
x-tool-secret: <ELEVENLABS_TOOL_SECRET>
Content-Type: application/json

{
  "user_id": "user_abc123",
  "op": "search",
  "command": "cat /mnt/s3files/shared/silvia-database-skills/SKILL.md"
}

​

Response

{
  "tool": "skills",
  "result": { "...": "tool-specific JSON or {\"raw\": \"...\"} if non-JSON" }
}

• 400 — malformed JSON body, missing tool name in URL, or missing/invalid user_id in body
• 401 — bad or missing x-tool-secret
• 403 — tool is not opted into the voice surface
• 500 — ELEVENLABS_TOOL_SECRET not configured, or the dispatcher itself threw before reaching the executor

​

Surface eligibility

• get_current_time
• skills (POSIX shell over the skills filesystem + persistent personal-memory writes — previously unreachable from voice; voice has the same op="search" | "write" | "delete" access chat does, since memory is shared across surfaces)
• send_email (parity with chat/SMS/email; voice already supports email via the legacy app/api/incoming-call-webhook-send-email-tool endpoint that the ElevenLabs system prompt drives — keeping it on the dispatcher avoids a regression once Phase 4 deletes the legacy routes)
• execute_sql (read financial data — radar queries and the financial-statement schedule are now expressed as SQL rather than dedicated tools)
• execute_python (Lambda microVM sandbox — Finnhub SDK, pandas, numpy, requests, S3 session save/load; also serves web search and historical/deep research, which no longer have standalone tools)

1. Append the snake_case name to VOICE_ALLOWED_TOOLS in the dispatcher.
2. Register a Server Tool with the same name in the ElevenLabs dashboard.

​

ElevenLabs agent configuration

• Method: POST
• URL: https://<app-host>/api/incoming-call-webhook-tool/skills
• Headers:
  • Content-Type: application/json
  • x-tool-secret: {{ELEVENLABS_TOOL_SECRET}} (from agent secret)
• Body template (JSON):
  {
    "user_id": "{{user_id}}",
    "op": "{{op}}",
    "command": "{{command}}",
    "filename": "{{filename}}",
    "content": "{{content}}"
  }
  
  Same input shape as the chat tool: op is search | write | delete, command is required for search, filename for write/delete, content for write. The dispatcher only checks the tool name — per-op argument validation happens inside the executor.
• Description / parameter schema: copy verbatim from the matching entry in regularTools in app/api/claude/tools/definitions.ts so the voice LLM sees the same tool docs the chat LLM gets.

​

Debugging

• [Voice Tool] Dispatching <tool_name> — accepted request (no clerkId in the dispatcher’s own log line to keep raw user identifiers out of every request log; per-user tracing flows through the shared tool-logger instead, same as chat/SMS/email)
• [Tool Execute] <tool_name>: — underlying executor logging (same as chat)
• [Voice Tool] Unauthorized dispatch attempt — 401
• [Voice Tool] Tool "<name>" is not enabled for voice surface — 403
• [Voice Tool] Dispatcher error: <error> — server-side-only log of the full exception; the client always receives a generic 500 body

​

Migration plan

1. Phase 2 (shipped) — dynamic [name] route added under the same directory. Static routes keep serving the 42 existing URLs; the dynamic route handles any new slug that has no static file.
2. Phase 3 — configure new ElevenLabs server tools at the new slugs (/skills, /execute_sql, etc.). Update the agent system prompt in the ElevenLabs dashboard to match the latest ./voice-system-prompt.md once it’s been updated to reference the new dispatcher tools. Staging canary first. No change to the 42 legacy tools during this phase — they keep working, giving us a risk-free rollback path.
3. Phase 4 — once production has baked on the new tools, delete the 42 static route directories. The dynamic [name] route handles everything that remains. ElevenLabs URLs are unchanged from Phase 3.