Skip to main content
This document covers athenahealth_get_encounter_documentation, the native AthenaHealth clinical documentation tool exposed through the Agents Platform.

​
Authentication

AthenaHealth tools use the existing AthenaHealth connector. Users configure client_id, client_secret, practice_id, and environment. Credentials are injected from the connector and are not shown as a per-run input.

​
athenahealth_get_encounter_documentation

Fetches raw AthenaHealth clinical documentation sections for an encounter. Despite the old name get_encounter_notes, this tool returns much more than narrative notes: structured HPI, assessment, ROS, vitals, diagnosis codes, procedure codes, procedure documentation, social history, patient goals, and practice modifiers. The tool is read-only.

​
Inputs

Required:
  • visit_id: AthenaHealth encounter ID.

​
Sections Fetched

The tool attempts to fetch:
  • Encounter assessment
  • Encounter reasons
  • HPI
  • Orders
  • Physical exam
  • Review of systems
  • Screeners / questionnaires
  • Vitals
  • Diagnosis codes
  • Procedure documentation
  • Presedation assessment
  • Procedure times
  • Procedure roles
  • Procedure timeout checklist
  • Patient goals
  • Social history
  • Practice modifiers
Intentionally excluded because the Athena routes are unusable for a generic encounter lookup:
  • Procedure codes (procedurecodes) — the route 404s with “An unknown API path was called”.
  • Stage procedure documentation (stageproceduredocumentation) and procedure vitals (procedurevitals) — require a stage field that cannot be supplied generically (HTTP 400 missingfields:["stage"]).
Empty sections (e.g. no orders/vitals/diagnoses for the encounter) are returned as empty data and labeled empty, not as errors. Social history is patient-scoped. Because the encounter header usually carries an appointmentid but no patientid, the tool resolves the patient (and department) through the appointment before fetching social history. Without this fallback, social history is silently skipped for most encounters.

​
Execution Flow

​
Partial Failure Behavior

The encounter header fetch is fatal. Individual section failures are non-fatal:
  • failed section value is set to null,
  • failure message is recorded under errors[SECTION_KEY],
  • fetched_count, failed_count, and total_count summarize coverage.

​
Output

Structured output includes:
  • success
  • practice_id
  • visit_id
  • encounter_header
  • notes: keyed documentation sections
  • errors: keyed section errors
  • fetched_count
  • failed_count
  • total_count
Example shape:

​
Human-readable text

The tool renders the full documentation as deterministic markdown so the UI shows complete output without relying on a downstream LLM formatter. Output includes:
  • an ## Encounter Documentation metadata table (visit name, date, type, appointment start, provider, phone, status, ids, last updated, sections fetched/total),
  • a ## <Section> block for every fetched section, ordered like a clinical note (reason → HPI → social history → ROS → physical exam → vitals → screeners → procedure sections → orders → diagnoses → assessment & plan → patient goals → practice modifiers). Narrative sections render as cleaned prose; structured sections (social history questions, procedure times, procedure roles, diagnoses, orders/vitals, modifiers, etc.) render as table cards. Sections with no content render _No data available._ (rather than being skipped); sections that returned only configured template entries with no values render a table with No value recorded; failed sections render _Could not load this section._.
  • a ## Data Sources table at the end giving every section’s status (OK / Empty / Template only / Error) with a one-line note (no endpoint column).
Narrative sections (assessment, procedure documentation) also append a _Last modified by … on …_ provenance footer when those fields are present. The task-feed renderer (GenericToolFeedItem) pulls each markdown table into its own card. splitProseHeading only consumes the heading immediately adjacent to a table as that table’s card title, so non-table narrative section headings are preserved while structured sections can still render as titled table cards. Rendering normalizes Athena’s payloads before display: HTML/templated summarytext/assessmenttext/proceduredocumentationtext strings are stripped to plain text, HTML entities (e.g. &#39;) are decoded, zero-width characters are removed, and sections/questions/procedureevents arrays are flattened into readable lists. Verbatim narrative tokens such as [+]/[-]/[0] are preserved. Full raw section bodies still remain in structuredContent for traceability.

​
Agent Instruction Guidance

Use this tool only after summary-level skip checks pass. For patient-context prompts, call it once for the target encounter and then fan out over nearby encounters returned by athenahealth_get_encounter_summary.