Schedule Appointment

Overview

schedule_appointment books an appointment by creating a FHIR Appointment resource. An LLM/agent should call this tool after the patient has selected a slot from get_scheduling_slots. It requires the selected start datetime, minutes_duration, and the same visit_type_id, provider_id, and department_id values used in get_scheduling_slots. The timezone value returned by get_scheduling_slots should be passed as timezone_title. On success it returns appointment confirmation with an ID.

Required Parameters

start (string)

• Appointment start as an ISO 8601 datetime with timezone offset (e.g. '2025-08-06T08:30:00-05:00').
• Use the start_date + start_time from a slot returned by get_scheduling_slots.

minutes_duration (integer)

• Duration of the appointment in minutes (e.g. 15).

visit_type_id (string)

• The same visit type code used in get_scheduling_slots.

provider_id (string)

• The same provider NPI used in get_scheduling_slots (from provider_search).

department_id (string)

• The same department/facility_id used in get_scheduling_slots (from provider_search).

Optional Parameters

comment (string)

• Default: ""
• Optional comment or reason for the visit.

timezone_title (string)

• Default: None
• Timezone title for the appointment (e.g. 'Central Standard Time', 'America/Chicago'). Use the timezone value from get_scheduling_slots.
• If not supplied, defaults to 'Central Standard Time'.

person_id (string)

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

debug (boolean)

• Default: false
• Whether to display debugging information.

Returns

Returns an AppointmentResult object with:

• appointment_id (string, optional) — The booked appointment ID.
• appointment_start_date (string, optional) — Start date of the booked appointment.
• appointment_type (string, optional) — Type of the booked appointment.
• patient_lookup_success (boolean, optional) — Whether the patient lookup/create step succeeded.
• 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 the final step of the new-appointment booking flow: get_visit_types → get_scheduling_slots → schedule_appointment.