Skip to content

Tool Inventory

14 active tools powering the v3.0 squad, with distribution matrix and request-start configuration

Last Updated: 2026-03-07 (v4.2.1 — tool parameter expansion + P1 fixes)

Summary

Category Count Status
Active function tools 14 In use by v3.0 squad
Legacy Google tools 3 Deprecated -- do NOT use
Legacy handler-only tools 5 In webhook handler only, no YAML, not called by v3.0

All 14 active tools point to the same backend: https://api-dev.vitaravox.ca/api/vapi/ (except find_earliest_appointment, which has no server block and uses the org-level tool definition). Tools are language-agnostic (the language parameter is supported where needed).

GitOps Slug References

In Vapi GitOps, tools are referenced by slug (e.g., search-patient-by-phone-8474536c), not by UUID. Each tool is defined once in resources/tools/ and referenced from assistant YAMLs. This eliminates inline JSON duplication.

Credential Strategy

Some tools use credentialId only (search-patient-by-phone, search-patient). Others also include hardcoded X-API-Key and Content-Type headers. This inconsistency is functional but should be reviewed for production.

Tool Reference (14 Tools)

1. search_patient_by_phone

Field Value
YAML File search-patient-by-phone-8474536c.yml
Slug search-patient-by-phone-8474536c
Vapi ID 8474536c-663f-4a94-91ae-19e6221f9af9
Server URL https://api-dev.vitaravox.ca/api/vapi/search-patient-by-phone
Timeout 20s
request-start Audible / non-blocking: "Let me pull up your file."
Assigned To Patient-ID EN, Patient-ID ZH

Parameters:

Param Type Required Description
phone string YES 10-digit phone number WITHOUT country code

Note

Server extracts the real phone from call.customer.number. The "0000000000" in prompt instructions is a placeholder -- the LLM never needs to know the actual phone number. Server always prefers callerPhone over the LLM argument.

2. search_patient

Field Value
YAML File search-patient-4889f4e5.yml
Slug search-patient-4889f4e5
Vapi ID 4889f4e5-b603-4e53-aa8a-1f3b97403f46
Server URL https://api-dev.vitaravox.ca/api/vapi/search-patient
Timeout 20s
request-start Silent / non-blocking
Assigned To Patient-ID EN, Patient-ID ZH

Parameters (YAML):

Param Type Required Description
name string YES Patient last name or full name
firstName string no Patient first name

Parameter Drift

The YAML defines name and firstName. The webhook handler destructures name (as patientName) and dateOfBirth -- it does NOT use firstName. If dateOfBirth is needed, add it to the YAML. If firstName is not needed, consider removing it from the YAML.

3. get_patient

Field Value
YAML File get-patient-d86dee47.yml
Slug get-patient-d86dee47
Vapi ID d86dee47-b34e-4cd9-a482-764be96b42a5
Server URL https://api-dev.vitaravox.ca/api/vapi/get-patient
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To (reserved -- not currently assigned to any v3.0 agent)

Parameters:

Param Type Required Description
demographicId integer YES Patient demographic ID

Note

Handler accepts both patientId and demographicId for backward compatibility.

4. get_clinic_info

Field Value
YAML File get-clinic-info-aaec50cf.yml
Slug get-clinic-info-aaec50cf
Vapi ID aaec50cf-fb55-4501-8363-5b2dba8a5761
Server URL https://api-dev.vitaravox.ca/api/vapi/get-clinic-info
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Router, Patient-ID EN, Patient-ID ZH

Parameters: None required.

Returns: Clinic name, address, phone, hours, acceptingNewPatients status, customGreeting, customGreetingZh, defaultProviderId, supportedLanguages, appointmentTypeMappings.

5. get_providers

Field Value
YAML File get-providers-1ffa2c33.yml
Slug get-providers-1ffa2c33
Vapi ID 1ffa2c33-16a2-41ee-9fb5-6e016400dede
Server URL https://api-dev.vitaravox.ca/api/vapi/get-providers
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Booking EN/ZH, Modification EN/ZH

Parameters:

Param Type Required Description
specialty string no Filter by specialty

Note

The webhook handler currently ignores the specialty parameter and returns all providers. Server-side filtering is not yet implemented.

6. find_earliest_appointment

Field Value
YAML File find-earliest-appointment-7fc7534d.yml
Slug find-earliest-appointment-7fc7534d
Vapi ID 7fc7534d-a838-4d46-97ef-3dc5e52d5bb8
Server URL (no server block -- org-level tool)
Timeout N/A
request-start Audible / non-blocking: "Let me check what's available."
Assigned To Booking EN/ZH, Modification EN/ZH

Parameters:

Param Type Required Description
startDate string no Start YYYY-MM-DD. Omit = today
endDate string no End YYYY-MM-DD. Omit = 30 days from start
timeOfDay enum no "morning" (before 12:00) or "afternoon" (12:00+)
providerId string no Numeric provider ID. Omit = search all
providerName string no Doctor name (e.g., "Dr. Smith") -- resolved server-side
excludeDates string[] no Dates to skip (YYYY-MM-DD)
visitMode string no "in-person" or "virtual" — filters providers by visit mode capability

Tip

Returns exactly one slot per call. Call again with different filters or excludeDates for alternatives. Non-numeric providerId values (e.g., "any", "任何") are treated as "search all providers".

7. check_appointments

Field Value
YAML File check-appointments-74246333.yml
Slug check-appointments-74246333
Vapi ID 74246333-9a06-4c68-80a2-964aa1a66563
Server URL https://api-dev.vitaravox.ca/api/vapi/check-appointments
Timeout Not configured in YAML
request-start Audible / non-blocking: "Let me look that up."
Assigned To Booking EN/ZH, Modification EN/ZH

Parameters:

Param Type Required Description
startDate string YES Start date YYYY-MM-DD
endDate string YES End date YYYY-MM-DD
demographicId integer no Patient ID (for existing bookings)
providerId string no Provider ID or "any"
findAvailable boolean no true = open slots, false = patient bookings

Note

Server accepts both "demographicId" and "patientId" for backward compatibility.

8. create_appointment

Field Value
YAML File create-appointment-65213356.yml
Slug create-appointment-65213356
Vapi ID 65213356-fbd3-4088-90b9-36dc98c73902
Server URL https://api-dev.vitaravox.ca/api/vapi/create-appointment
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Booking EN/ZH, Modification EN/ZH

Parameters:

Param Type Required Description
demographicId integer YES Patient demographic ID
providerId string YES Provider ID
startTime string YES ISO format YYYY-MM-DDTHH:MM:00
appointmentType string YES OSCAR code: "B", "2", "3", "P" (validated against clinic config)
reason string YES Reason for visit
language string YES "en" or "zh"
smsConsent boolean no true (default, opt-out model) or false if patient declined texts
isVirtual boolean no True for phone/video appointments
visitMode string no "in-person" or "virtual" (from provider config)
visitReason string no Visit reason (from provider config, e.g., "General Visit")
isNewPatient boolean no Whether patient is new (from conversation context)
preferredTime string no Preferred time slot (from provider config)

Response includes:

Field Type Description
success boolean Whether booking succeeded
appointmentId integer OSCAR appointment ID (on success)
smsSent boolean Whether SMS confirmation was triggered (check this to decide whether to mention "text confirmation")
message string Human-readable confirmation or error

Warning

Server checks for slot collisions before booking via BookingEngine and sends status "t" (To Do) to OSCAR. Always verify the tool returns success before confirming to the caller.

v3.1 Provider Config Parameters

The visitMode, visitReason, isNewPatient, and preferredTime parameters are populated from the provider-level configuration (see Architecture: Provider Configuration). If not provided by the LLM, the server resolves defaults from the 3-level inheritance chain.

9. update_appointment

Field Value
YAML File update-appointment-635f59ef.yml
Slug update-appointment-635f59ef
Vapi ID 635f59ef-9fe0-4a27-9221-13d1ea858840
Server URL https://api-dev.vitaravox.ca/api/vapi/update-appointment
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Modification EN/ZH

Parameters:

Param Type Required Description
appointmentId integer YES Existing appointment ID
newStartTime string YES New time ISO format
newProviderId string no New provider ID if changing
demographicId string no Patient demographic ID from conversation context
smsConsent boolean no true (default) or false if patient declined texts

Response includes: smsSent (boolean) — whether SMS confirmation was triggered for the reschedule.

Reschedule Strategy

Server books the NEW appointment FIRST, then cancels the old one. If the new booking fails, the patient keeps their original appointment.

10. cancel_appointment

Field Value
YAML File cancel-appointment-f6cef2e7.yml
Slug cancel-appointment-f6cef2e7
Vapi ID f6cef2e7-aa33-41d8-be98-fe4574091516
Server URL https://api-dev.vitaravox.ca/api/vapi/cancel-appointment
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Modification EN/ZH

Parameters:

Param Type Required Description
appointmentId integer YES Appointment ID to cancel
reason string no Reason for cancellation
language string no "en" or "zh" (for SMS template selection)
smsConsent boolean no true (default) or false if patient declined texts

Response includes: smsSent (boolean) — whether SMS cancellation notice was triggered.

Note

Tool description instructs the LLM: "ONLY call after patient confirms twice." Double confirmation is required before cancellation.

11. register_new_patient

Field Value
YAML File register-new-patient-9a888e09.yml
Slug register-new-patient-9a888e09
Vapi ID 9a888e09-1ede-4ec5-a683-dd376cd3133d
Server URL https://api-dev.vitaravox.ca/api/vapi/register-patient
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Registration EN/ZH

Parameters:

Param Type Required Description
firstName string YES First name
lastName string YES Last name
dateOfBirth string YES DOB YYYY-MM-DD
gender string YES "M", "F", or "O"
phone string YES Phone number
address string YES Street address
city string YES City
postalCode string YES Postal code
healthCardType string YES "BC", "OUT_OF_PROVINCE", or "PRIVATE"
language string YES "en" or "zh"
province string no Province (default BC)
email string no Email
healthCardNumber string no BC PHN 10 digits

12. add_to_waitlist

Field Value
YAML File add-to-waitlist-0153bac0.yml
Slug add-to-waitlist-0153bac0
Vapi ID 0153bac0-5224-45df-af84-0ccd27befb9a
Server URL https://api-dev.vitaravox.ca/api/vapi/add-to-waitlist
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Registration EN/ZH

Parameters:

Param Type Required Description
firstName string YES First name
lastName string YES Last name
phone string YES Phone for callback
notes string no Notes

13. transfer_call

Field Value
YAML File transfer-call-d95ed81e.yml
Slug transfer-call-d95ed81e
Vapi ID d95ed81e-002c-449f-9469-d35e86594b2d
Server URL https://api-dev.vitaravox.ca/api/vapi/transfer-call
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Router, Patient-ID EN/ZH, Booking EN/ZH, Modification EN/ZH, Registration EN/ZH

Parameters (YAML):

Param Type Required Description
reason string YES One of: patient_request, frustrated, medical_question, billing, registration_error, record_not_found, out_of_scope
notes string no Brief notes for staff

Parameter Name Mismatch

The YAML sends notes but the webhook handler destructures context. The notes field value will be ignored by the server. Either rename the YAML parameter to context or update the handler to accept notes.

14. log_call_metadata

Field Value
YAML File log-call-metadata-4619b3cb.yml
Slug log-call-metadata-4619b3cb
Vapi ID 4619b3cb-8bd7-489d-a807-1980d82ccb1d
Server URL https://api-dev.vitaravox.ca/api/vapi/log-call
Timeout Not configured in YAML
request-start Silent / non-blocking
Assigned To Router, Booking EN/ZH, Modification EN/ZH, Registration EN/ZH

Parameters:

Param Type Required Description
language string YES "en" or "zh"
callOutcome string YES One of: booked, rescheduled, cancelled, registered, waitlisted, transferred, no_action
appointmentId integer no Appointment ID if booking was made
demographicId integer no Patient demographic ID if identified

v2.3.0 vs v3.0

In v2.3.0, log_call_metadata was assigned only to the Confirmation agent. In v3.0, it is distributed to Booking, Modification, Registration, and Router, enabling the elimination of the Confirmation agent. Metadata is cached in memory and merged into the call log when the end-of-call-report arrives.

Tool Distribution Matrix

Derived from actual assistant YAML frontmatter toolIds:

Tool Router Patient-ID EN Patient-ID ZH Booking EN Booking ZH Modification EN Modification ZH Registration EN Registration ZH
search_patient_by_phone X X
search_patient X X
get_patient
get_clinic_info X X X
get_providers X X X X
find_earliest_appointment X X X X
check_appointments X X X X
create_appointment X X X X
update_appointment X X
cancel_appointment X X
register_new_patient X X
add_to_waitlist X X
log_call_metadata X X X X X X X
transfer_call X X X X X X X X X

Tool counts per role:

Role Tool Count
Router 3 (get_clinic_info, transfer_call, log_call_metadata)
Patient-ID (EN/ZH) 4 (search_patient_by_phone, search_patient, get_clinic_info, transfer_call)
Booking (EN/ZH) 6 (find_earliest_appointment, check_appointments, create_appointment, get_providers, log_call_metadata, transfer_call)
Modification (EN/ZH) 8 (check_appointments, find_earliest_appointment, update_appointment, cancel_appointment, create_appointment, get_providers, log_call_metadata, transfer_call)
Registration (EN/ZH) 4 (register_new_patient, add_to_waitlist, log_call_metadata, transfer_call)

request-start Messages (from YAML source of truth)

Tool request-start Audible? Blocking?
search_patient_by_phone "Let me pull up your file." Yes No
find_earliest_appointment "Let me check what's available." Yes No
check_appointments "Let me look that up." Yes No
search_patient "" No No
get_patient "" No No
get_clinic_info "" No No
get_providers "" No No
create_appointment "" No No
update_appointment "" No No
cancel_appointment "" No No
register_new_patient "" No No
add_to_waitlist "" No No
transfer_call "" No No
log_call_metadata "" No No 
request-start MESSAGE TIMING

  Vapi LLM              Vapi Platform              Vitara Server
     │                       │                          │
     │ ──tool_call──────────►│                          │
     │                       │                          │
     │                       │── request-start ──►      │
     │                       │   (TTS plays if          │
     │                       │    message non-empty)    │
     │                       │                          │
     │                       │── POST /api/vapi/ ──────►│
     │                       │                          │ (handler runs)
     │                       │                          │
     │                       │◄── tool result ──────────│
     │                       │                          │
     │◄── tool result ───────│                          │
     │                       │                          │
     │ (LLM speaks result)   │                          │

  AUDIBLE (3 tools):  search_patient_by_phone,
                      find_earliest_appointment,
                      check_appointments

  SILENT (11 tools):  Empty string "" — no TTS played

Design Rationale

  • Audible (3 tools): Tools that take 1-5 seconds and where the caller would otherwise hear dead air
  • Silent (11 tools): Tools that are called as part of a multi-tool sequence, or where the LLM will immediately speak the result
  • The FILLER PHRASE RULES sections were deleted from Booking and Modification prompts because request-start handles filler at the tool level

GitOps File Structure

Tools are defined once in the GitOps repository and referenced by slug from assistant YAMLs:

vitara-platform/vapi-gitops/
  resources/tools/
    search-patient-by-phone-8474536c.yml    # 8474536c
    search-patient-4889f4e5.yml             # 4889f4e5
    get-patient-d86dee47.yml                # d86dee47
    get-clinic-info-aaec50cf.yml            # aaec50cf
    get-providers-1ffa2c33.yml              # 1ffa2c33
    find-earliest-appointment-7fc7534d.yml  # 7fc7534d
    check-appointments-74246333.yml         # 74246333
    create-appointment-65213356.yml         # 65213356
    update-appointment-635f59ef.yml         # 635f59ef
    cancel-appointment-f6cef2e7.yml         # f6cef2e7
    register-new-patient-9a888e09.yml       # 9a888e09
    add-to-waitlist-0153bac0.yml            # 0153bac0
    transfer-call-d95ed81e.yml              # d95ed81e
    log-call-metadata-4619b3cb.yml          # 4619b3cb

Push changes with:

cd /home/ubuntu/vitara-platform/vapi-gitops && npm run push:dev

Environment Key

The Vapi GitOps environment variable is VAPI_TOKEN (not VAPI_API_KEY) in .env.dev.

Legacy Tools (Do NOT Use)

Vapi Org Legacy (Google integration)

Tool Vapi ID Type Notes
google_sheets_tool 639f3c7c-... google.sheets.row.append Pre-OSCAR era
google_calendar_tool 7a48f843-... google.calendar.event.create Pre-OSCAR era
google_calendar_check_availability ecde6b97-... google.calendar.availability.check Pre-OSCAR era

Webhook Handler Legacy (no YAML, not called by v3.0)

Handler Case Purpose
getUpcomingAppointments Legacy v1 appointment fetch
get_available_slots / getAvailableSlots Superseded by find_earliest_appointment
findAppointmentByPreference Legacy natural-language preference search
checkNewPatientAcceptance Legacy acceptance check (now in get_clinic_info response)
sendConfirmationSMS Legacy stub — replaced by Telnyx SMS in create/update/cancel_appointment tools (see SMS Integration)

Server URL Map

All 14 active tools point to https://api-dev.vitaravox.ca/api/vapi/:

Endpoint Tool
/search-patient-by-phone search_patient_by_phone
/search-patient search_patient
/get-patient get_patient
/get-clinic-info get_clinic_info
/get-providers get_providers
/check-appointments check_appointments
/create-appointment create_appointment
/update-appointment update_appointment
/cancel-appointment cancel_appointment
/register-patient register_new_patient
/add-to-waitlist add_to_waitlist
/transfer-call transfer_call
/log-call log_call_metadata
(org-level, no inline URL) find_earliest_appointment

Note

find_earliest_appointment has no server block in its YAML. It uses the org-level tool definition. All URL sub-paths are handled by the same Express handler (POST / and POST /:path); routing is done by function name, not by URL path.

Known Issues

Issue Severity Detail
transfer_call notes vs context P2 YAML param notes is not read by handler (expects context)
search_patient missing dateOfBirth P2 Handler uses it, YAML does not define it
search_patient unused firstName P3 YAML defines it, handler ignores it
get_providers specialty ignored P3 YAML defines specialty param, handler does not filter
Missing timeoutSeconds on 12 tools P3 Only search-patient-by-phone and search-patient have explicit timeout

P1 Issues Resolved (2026-03-04)

transfer_call added to 6 agents (Patient-ID EN/ZH, Booking EN/ZH, Registration EN/ZH). Past-date clamp added to bookAppointment handler. EMR adapter warmUp fix deployed on PM2 startup.