Get Scheduling Slots

Overview

get_scheduling_slots retrieves available scheduling slots (FHIR Slot resources) for a given provider, department, and visit type. An LLM/agent should call this tool when a patient wants to find available appointment times. It returns a list of available time slots with start/end datetimes and a timezone. All three IDs are required: visit_type_id (from the visit-type workflow), provider_id (the NPI from provider_search), and department_id (the facility_id from provider_search). If not supplied, the date range defaults to tomorrow through two weeks out.

Required Parameters

visit_type_id (string)

• The visit type code to search slots for.

provider_id (string)

• The provider's NPI number, as returned in provider_search results (e.g. '1407856023').

department_id (string)

• The facility_id from provider_search results (e.g. '222126').

Optional Parameters

person_id (string)

• Default: None
• The b.well FHIR Person ID (BwellClientFhirPersonID). Optional for the default patient.

start_date (string)

• Default: None
• Start date for the slot search, in YYYY-MM-DD format.
• Defaults to tomorrow if not supplied.

end_date (string)

• Default: None
• End date for the slot search, in YYYY-MM-DD format.
• Defaults to two weeks from today if not supplied.

count (integer)

• Default: None
• Maximum number of slots to return.

debug (boolean)

• Default: false
• Whether to display debugging information.

Returns

Returns a SchedulingSlotsResult object with:

• fhir_patient_id (string, optional) — The FHIR patient ID resolved from patient identifiers.
• count (integer, optional) — Total number of available slots.
• slots (list, optional) — The available scheduling slots. Each slot has:
  • start_date (string) — Start date of the slot (YYYY-MM-DD).
  • start_time (string) — Start time of the slot (HH:MM:SS).
  • end_date (string, optional) — End date of the slot (YYYY-MM-DD).
  • end_time (string, optional) — End time of the slot (HH:MM:SS).
• timezone (string, optional) — Timezone for the returned slots.
• last_scanned_date (string, optional) — Last date scanned for availability.
• Also includes the shared base result fields: result, error, urls, meta, and debug (the latter two populated only when debug=true).

Notes

• This tool is typically called after get_visit_types as part of the new-appointment booking flow: get_visit_types → get_scheduling_slots → schedule_appointment. The visit_type_id, provider_id, and department_id used here should be reused as-is when calling schedule_appointment.
• It is also used during rescheduling, after get_appointments identifies the appointment to move: get_appointments → get_scheduling_slots → reschedule_appointment.