> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AthenaHealth Get Encounter Summary

> Native AthenaHealth encounter summary tool exposed through the Agents Platform.

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

```mermaid theme={null}
flowchart TD
  agent[Agent] --> tool[athenahealth_get_encounter_summary]
  tool --> encounter[GetEncounter]
  encounter --> apptId[ExtractAppointmentID]
  apptId --> appointment[GetAppointment]
  encounter --> patientId[ResolvePatientID]
  appointment --> patientId
  patientId --> patient[GetPatient]
  patientId --> insurance[GetPatientInsurances]
  encounter --> window[BuildNearbyWindow]
  appointment --> nearby[ListBookedAppointments]
  patientId --> nearby
  nearby --> result[StructuredSummary]
```

### 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:

```json theme={null}
{
  "success": true,
  "practice_id": "1959408",
  "visit_id": "12345",
  "appointment_id": "98765",
  "patient_id": "111",
  "summary": {
    "patient_name": "Jane Smith",
    "insurances_found": 1,
    "procedure_codes_found": 0,
    "appointments_found": 2,
    "encounter_date": "05/01/2026",
    "encounter_type": "Office Visit",
    "provider": "Dr. Adams",
    "status": "checked out"
  },
  "procedure_codes": [],
  "errors": {}
}
```

### 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:

```text theme={null}
1. Call AthenaHealth: get encounter summary first.
2. Use procedure_codes_found, status, department, appointment type, and nearby appointments for deterministic skip checks.
3. If the encounter is codeable, call AthenaHealth: get encounter documentation and patient-level signal tools.
4. If reason is athenahealth_not_connected, ask the user to connect AthenaHealth or stop the task.
```