Get Upcoming Appointments

Overview

get_upcoming_appointments retrieves a patient's upcoming appointments from their healthcare schedule. An LLM/agent should call this tool when a patient asks about future appointments, scheduled visits, or what's coming up on their calendar — for example, "What appointments do I have coming up?", "When is my next appointment?", "What do I need to prepare for?", "Where is my appointment on [date]?", or "Who am I seeing next week?". It queries both FHIR Appointment and Encounter resources in parallel (some systems record future visits as Encounters rather than Appointments) and returns a merged, de-duplicated, chronologically ordered list of upcoming visits, excluding cancelled ones.

Optional Parameters

person_id (string)

• Default: None
• The identifier of the person whose appointments are to be retrieved.
• If not provided, the tool attempts to extract it from the caller's access token.

patient_id (string)

• Default: None
• The FHIR patient identifier to search appointments for.
• If not provided, the tool attempts to extract it from the caller's access token.

days_ahead (integer)

• Default: 365
• How far into the future to look for appointments, in days, measured from today.

count (integer)

• Default: 100
• Maximum number of appointments to return, applied after merging and de-duplicating results from both the Appointment and Encounter queries.

debug (boolean)

• Default: false
• Whether to include debugging information (the FHIR request URLs and retrieval timing/debug metadata) in the response.

Returns

Returns an UpcomingAppointmentResult object with the following fields:

• appointments (list of objects) — The list of upcoming appointments, each an UpcomingAppointmentItem with:
  • appointment_id (string) — Unique identifier for the appointment or encounter.
  • source_type (string) — The FHIR resource type the item came from: Appointment or Encounter.
  • start_datetime (datetime) — Start date and time of the appointment.
  • end_datetime (datetime, optional) — End date and time of the appointment.
  • status (string) — Status of the appointment (e.g., booked, pending, fulfilled, cancelled).
  • location_name (string, optional) — Name of the location where the appointment will take place.
  • location_address (string, optional) — Full address of the appointment location. Not currently populated by the retriever (reserved for a future enhancement that resolves the referenced Location resource).
  • practitioner_name (string, optional) — Name of the practitioner the patient is seeing.
  • practitioner_id (string, optional) — Unique identifier for the practitioner.
  • practitioner_specialty (string, optional) — Specialty of the practitioner (e.g., Cardiology, Primary Care). Only populated for items sourced from Appointment resources.
  • reason_for_visit (string, optional) — Reason for the appointment or the service type.
  • description (string, optional) — Additional description or notes about the appointment.
• total_count (integer) — Total number of appointments returned after merging, de-duplicating, and applying count.
• error (string, optional) — Populated if the underlying Appointment and/or Encounter FHIR query failed; when both fail, both error messages are included, separated by ; .
• urls (list of strings, optional) — Present only when debug=true; contains the FHIR request URL(s) used for the Appointment and Encounter queries.
• debug (object, optional) — Present only when debug=true; includes retrieval timing and request details from the Appointment query.

Notes

• Both Appointment and Encounter resources are queried in parallel for the same patient/person and date window (today through days_ahead days out), then merged into a single list. Appointment queries exclude cancelled and entered-in-error statuses; Encounter queries exclude finished, cancelled, and entered-in-error statuses.
• De-duplication matches items across the two resource types using a composite key of start time plus practitioner ID/name, since the same visit can appear as both an Appointment and an Encounter. When a duplicate is found, the Appointment-sourced item is kept over the Encounter-sourced one. The final list is sorted by start_datetime, earliest first.
• "Upcoming" is determined strictly by comparing timestamps to the current time: an item is included only if its start time (or, if start is missing, its end time) is in the future — naive timestamps are treated as UTC.
• Appointment/Encounter resources missing required fields (no ID, or no start time for Appointments / no period.start for Encounters) are skipped and logged, not returned as errors.
• Caching is disabled for both underlying FHIR queries (cache_ttl_seconds=0), so every call performs a live fetch.
• Requires a valid OAuth access token, obtained the same way as other tools in this server (via the request context).