DrChrono Push Eligibility Results - Nanonets Agents Platform

This document covers drchrono_push_eligibility_results, the DrChrono eligibility write-back tool exposed through the Agents Platform. DrChrono has no note field on a patient chart, so a verification of benefits is filed as a document. The tool renders the note as a one-page-or-more PDF and uploads it to the chart.

Authentication

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.

Safety

This is a mutating tool. Each successful call adds one document to a patient chart. It will not write in any of these cases:

No DrChrono patient matches the name and date of birth given.
The name search examined more charts than its cap and matched none of them. Correctness does not rely on DrChrono’s date_of_birth query filter — candidates are re-checked in full — so a cut-short search is reported as cut short rather than as a miss.
More than one patient matches. The error lists the candidate ids; re-run with patient_id to pick one.
patient_id was supplied but its chart carries a different date of birth.
The chart has no primary doctor. The documents API requires one as the filing provider.
A live (non-archived) document with the same title is already on the chart.

The date of birth is checked on every path, including when patient_id is supplied. A benefits note filed on the wrong chart is a PHI disclosure, so the tool refuses rather than guesses. The tool does not change the insurance record on file. The AthenaHealth tool of the same name offers that as an action; this one does not, because an eligibility check verifies coverage rather than correcting it.

Inputs

Required:

date_of_birth: YYYY-MM-DD or MM/DD/YYYY. Always required — it confirms the chart before the write.
benefits_note: the finished note, filed verbatim.

Identify the chart with either:

patient_id: the DrChrono patient ID. Never an ID from another EHR.
first_name and last_name.

Optional:

date_of_service: YYYY-MM-DD or MM/DD/YYYY. Sets the document date and title. Defaults to today.

What lands on the chart

Field	Value
Description	`VOB: MM/DD/YYYY` (the date of service)
File name	`VOB_MM-DD-YYYY.pdf`
Metatag	`VOB`
Date	the date of service
Doctor	the patient’s primary doctor

These match what the Nanonets Health EBV agent writes, so a VOB filed by an agent and one filed by that pipeline look the same in the chart and answer the same filters.

Output

{
  "success": true,
  "written": true,
  "skipped": false,
  "patient_id": "555",
  "doctor_id": "77",
  "document_id": "9911",
  "description": "VOB: 09/01/2026",
  "file_name": "VOB_09-01-2026.pdf",
  "date": "2026-09-01",
  "metatags": ["VOB"]
}

When the document is already on the chart, written is false, skipped is true, and reason is document_already_exists. document_id points at the existing document, and is omitted when DrChrono did not return an id for it — an absent id is reported as absent rather than as a placeholder. Treat this outcome as success — do not retry it.

Failure outcomes

Every failure carries a reason and a retryable flag, so a caller can tell a deterministic refusal from a call worth retrying. A refusal will refuse again on identical input; retrying it only wastes a call.

`reason`	`retryable`	Meaning
`invalid_arguments`	no	A required field is missing, or a date or `patient_id` could not be parsed.
`patient_not_found`	no	No chart matches the name and date of birth.
`patient_ambiguous`	no	More than one chart matches. 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 — re-run with `patient_id`.
`date_of_birth_mismatch`	no	The `patient_id` given belongs to a chart with a different date of birth.
`no_primary_doctor`	no	The chart has no primary doctor, so it cannot take a document.
`lookup_failed`	yes	A DrChrono read failed. Nothing was written — the duplicate check fails closed, because it is the only thing stopping a second VOB.
`upload_failed`	yes	The document POST failed.
`client_unavailable`	yes	The DrChrono client could not be built.

Each failure also carries suggested_actions — the same shape the not-connected result uses.

Limits

Up to three upstream DrChrono operations per invocation: the patient lookup, the document list, and the upload.
A name search examines at most 500 charts, paged 250 at a time. Beyond that it reports patient_search_truncated instead of a result.
The duplicate check pages the chart’s documents 250 at a time, up to the client’s 20-page ceiling.
The PDF uses the base-14 Helvetica face, which is Latin-1. Characters outside it (an em dash, a curly quote) are replaced with ?.

Human-readable text

The tool emits a markdown field table for the feed — Written to DrChrono or Already on file — carrying the patient id, the filing doctor, the document title and id, the file name and the metatag. The full payload stays in structuredContent.

Agent Instruction Guidance

Pass the note exactly as the previous step produced it. Do not shorten or reformat it. Push one document per patient. When several patients were processed, make one call each, with that patient’s own note. Retry only when the result says retryable: true, and then at most once. Each successful call adds another document, so a blind retry loop stacks duplicates on the chart — the duplicate check only catches a repeat of the same title. On a refusal, report the message and the suggested_actions to the user rather than working around it. patient_ambiguous is resolved by re-running with patient_id, not by picking one.

​Authentication

​Safety

​Inputs

​What lands on the chart

​Output

​Failure outcomes

​Limits

​Human-readable text

​Agent Instruction Guidance