Skip to main content
This document covers athenahealth_get_encounter_summary, the native AthenaHealth encounter summary tool exposed through the Agents Platform.

​
Authentication

AthenaHealth tools use the existing AthenaHealth connector. Users configure:
  • client_id
  • client_secret
  • practice_id
  • environment
The connector performs AthenaHealth’s OAuth client credentials flow, caches the bearer token, and refreshes it when needed. Tools do not accept a raw Athena access token or caller-supplied API base URL.

​
athenahealth_get_encounter_summary

Fetches a read-only AthenaHealth encounter by visit_id, then enriches it with related appointment, patient demographics, patient insurances, existing procedure codes, and booked appointments near the encounter date. This tool is intended to be the first Athena step in realtime coding. It returns enough information for cheap deterministic skip checks before the workflow spends API/LLM budget on full documentation.

​
Inputs

Required:
  • visit_id: AthenaHealth encounter ID. Treat this as an opaque string.
Optional:
  • appointment_window_days: Days on either side of the encounter date for nearby booked appointments. Defaults to 5 and is capped at 30.

​
Execution Flow

​
Lookup Behavior

The tool:
  • fetches /chart/encounter/{visit_id},
  • fetches the related appointment when appointmentid is present,
  • resolves patientid from the encounter first, then the appointment,
  • fetches patient demographics and insurances when possible,
  • builds a nearby appointment window from the encounter date,
  • fetches nearby booked appointments when patient and provider/department context is available.
The main encounter fetch is fatal. Later enrichment failures are non-fatal and are returned under errors.

​
Output

On success, structured content is a typed EncounterSummaryResult envelope (with a typed EncounterSummaryInfo summary block and a typed []Appointment appointments slice). The encounter, appointment, patient, insurances, and procedure_codes fields are retained as raw upstream passthrough so no AthenaHealth field is dropped. The JSON shape is unchanged. It includes:
  • success: true
  • practice_id
  • visit_id
  • appointment_id
  • patient_id
  • summary
  • encounter
  • appointment
  • patient
  • insurances
  • procedure_codes
  • appointments
  • errors
Example shape:

​
Human-readable text

In addition to the structured content above, the tool emits a markdown text block so the related detail is visible in the task feed (the generic feed renderer shows the markdown directly). It contains:
  • ## Encounter Summary — the core summary table (practice, visit, patient, counts, diagnoses, provider, department, chart ID, status, last updated).
  • ## Appointment — the primary appointment: ID, type, date, start time, duration, department, status, copay, charge-entry flag, rendering/supervising provider, urgent (omitted when no appointment resolved).
  • ## Patient — name, patient ID, DOB, sex, status, marital status, address, home phone, email, department, registration date (omitted when no patient resolved).
  • ## Insurance (N) — one row per insurance: sequence, payer, plan, member ID, type, eligibility, last checked, policy holder, phone, relationship (omitted when none).
  • ## Nearby Appointments (N) — for each appointment in the window: appointment ID, date, start time, type, status, encounter status, check-in, check-out, provider, visit ID, encounter ID, reason (omitted when none).
Empty sections are skipped so the block only renders what was actually fetched. Common failure reasons:
  • athenahealth_not_connected: AthenaHealth is not connected.
  • Main encounter lookup fails: return a tool error.
  • Partial enrichment errors: returned under errors while preserving available data.

​
Agent Instruction Guidance

Recommended realtime coding workflow: