DrChrono Get Patient - Nanonets Agents Platform

This document covers drchrono_get_patient, the DrChrono patient-lookup tool exposed through the Agents Platform. It is the DrChrono counterpart of athenahealth_get_patient: it answers “who is this patient and what are they insured under” for a patient whose chart lives in DrChrono.

Authentication and enablement

Uses the DrChrono OAuth connector. The platform injects access_token; the agent never supplies it. When DrChrono is not connected, the tool returns reason: "drchrono_not_connected" rather than an error, so the agent can ask the user to connect it. It is off by default — enable it on the agent.

Inputs

Identify the chart one of two ways:

patient_id — the DrChrono patient ID. A value a variable resolved to a float (555.0) is normalized to 555; a non-numeric value fails locally before any call.
first_name, last_name and date_of_birth, together. A name alone is refused: DrChrono matches names on a prefix, and the date of birth is what narrows a name to one person.

Optional:

date_of_birth alongside patient_id. When given, it must match the chart, or the tool refuses with date_of_birth_mismatch.

Dates accept YYYY-MM-DD or MM/DD/YYYY.

A patient_id must be a DrChrono ID. AthenaHealth and DrChrono number patients independently and reuse the same numbers for different people, so passing an AthenaHealth ID here can return a different, real patient.

Output

{
  "success": true,
  "found": true,
  "ehr": "drchrono",
  "patient_id": "555",
  "patient": {
    "id": "555",
    "first_name": "MISTY",
    "middle_name": "A",
    "last_name": "LEWIS",
    "date_of_birth": "1980-10-27",
    "doctor_id": "77",
    "chart_id": "LEMI000001",
    "gender": "Female",
    "patient_status": "A",
    "address": "12 Desert Rd",
    "city": "Henderson",
    "state": "NV",
    "zip_code": "89002",
    "cell_phone": "(702) 555-0100",
    "email": "misty@example.com"
  },
  "insurances": [
    {
      "sequence": "Primary",
      "payer_name": "SelectHealth",
      "payer_id": "SX107",
      "member_id": "802385112",
      "group_number": "G-100",
      "group_name": "Acme Corp",
      "plan_name": "SelectMed",
      "plan_type": "PPO",
      "subscriber_is_patient": true,
      "relationship_to_subscriber": "18",
      "subscriber_first_name": "MISTY",
      "subscriber_last_name": "LEWIS",
      "subscriber_date_of_birth": "1980-10-27"
    }
  ]
}

insurances holds DrChrono’s filled insurance slots in billing order — Primary, then Secondary, then Tertiary. An unused slot is left out, and insurances is always a list: a patient with no coverage on file returns []. The field names follow eligibility vocabulary (member_id, payer_name) so an agent maps them the way it maps AthenaHealth plans. DrChrono keeps no per-plan eligibility status; the Primary slot is the coverage the practice bills first.

What is deliberately not returned

The record is curated, not DrChrono’s raw payload. DrChrono’s verbose patient record carries the patient’s Social Security number, the subscriber’s Social Security number, and insurance-card photos. None of them is needed to check eligibility, and whatever this tool returns is placed in a model’s context, so they are dropped when the response is decoded and never leave the tool. This is a deliberate difference from athenahealth_get_patient, which returns the AthenaHealth record as-is.

Failure outcomes

Every failure carries a reason and a retryable flag.

`reason`	`retryable`	Meaning
`invalid_arguments`	no	No usable identifier, an unparseable date, or a non-numeric `patient_id`.
`patient_not_found`	no	DrChrono has no patient with that ID, or no chart matches the name and date of birth.
`patient_ambiguous`	no	More than one chart matches the name and date of birth. The message lists the IDs.
`patient_search_truncated`	no	More same-name charts exist than the search examined, and none of those examined matched. This is not proof the chart is absent.
`date_of_birth_mismatch`	no	The `patient_id` names a chart with a different date of birth.
`lookup_failed`	yes	A DrChrono call failed. The patient may well exist — this means DrChrono could not be asked.
`client_unavailable`	yes	The DrChrono client could not be built.

patient_not_found and lookup_failed are kept strictly apart. DrChrono answering “no such patient” (HTTP 404) is a definitive result; a timeout or a 5xx is not, and is never reported as a miss.

Limits and side effects

Read-only; no writes. A lookup by ID makes two GETs — the chart, then the verbose read that carries the insurance. A name search adds one paged search first, examining at most 500 charts 250 at a time. Chart identification is shared with drchrono_push_eligibility_results, so a lookup and a later write agree on which patient a query names and refuse for the same reasons.

Human-readable text

The tool emits a ## Patient field table — status, patient ID, name, date of birth, state, chart ID, primary doctor ID, and patient status — and a ## Insurance table with one row per plan: sequence, payer, member ID, group, plan type, and relationship to subscriber. With no plans on file the insurance section says so.

Agent instruction guidance

Call it when you hold a DrChrono patient ID, or a full name with date of birth, and the next step needs demographics or coverage — typically building an eligibility check for a patient who is not in AthenaHealth. When a request carries a bare patient ID and does not say which EHR it came from, look it up in both AthenaHealth and DrChrono and compare, rather than trying one and falling back to the other. Because the two systems reuse numbers, a fallback can turn an AthenaHealth miss — or an AthenaHealth outage — into a confident match on the wrong DrChrono patient. Treat lookup_failed as “unknown”, never as “not here”.

​Authentication and enablement

​Inputs

​Output

​What is deliberately not returned

​Failure outcomes

​Limits and side effects

​Human-readable text

​Agent instruction guidance