Skip to main content

​
What these tools are

The AdvancedMD integration exposes two kinds of tool. The hand-written ones (advancedmd_post_payment, advancedmd_update_appointment_type, and so on) implement multi-step workflows: they make several API calls, resolve carriers, run pre-post balance checks, and fall back deliberately when AdvancedMD answers oddly. The tools on this page are different. Each one is a single AdvancedMD API call, described declaratively in an operation catalog rather than implemented in code. They are named advancedmd_op_<operation> and there are 39 of them. Use a workflow tool when one exists for your task. Reach for these when you need an AdvancedMD endpoint that no workflow tool covers.

​
Authentication and enablement

All of these tools read the workspace’s AdvancedMD integration — office code, username and password — from the connected integration. Those fields are never supplied by the agent and are not part of the model-visible schema. If AdvancedMD is not connected, the tool returns a “not connected” result rather than failing the task. Every operation is disabled by default. Enable the specific ones an agent needs; do not enable all 39.

​
Inputs and outputs

Each tool’s inputs are exactly the arguments its operation declares — the schema and each field’s description come from the catalog, so what you see in the tool picker is what AdvancedMD accepts. Patient and visit ids are reshaped automatically where AdvancedMD is inconsistent about them (some actions want pat11506958, others reject the prefix and want 11506958). Every result carries:
  • success — whether a declared result path actually resolved. Not merely whether the call returned: AdvancedMD answers a rejected request with HTTP 200 often enough that “no error” is not evidence of anything.
  • operation — the operation name, echoed back.
  • data — the projected records.
  • matched_at — where in AdvancedMD’s response the data was found. Present only when a path resolved.
  • message — present only when no path resolved, saying that the empty data is not evidence the record does not exist.
  • warnings — present only when the response arrived in a different envelope than expected.
A result whose path resolved (and every dry run) is stored as a task variable, named in the “Output stored as VARN"lineafterthecall.Passittoalatertoolbyreference,forexample‘{VAR_N}" line after the call. Pass it to a later tool by reference, for example `.data` into a Python step. Because a read holds patient data, the variable is never injected into other tool calls automatically; a tool receives it only where its arguments reference it. A result that did not resolve stores nothing.

​
Rehearsing a write

Every write accepts dry_run. With dry_run: true the tool builds the request, returns it, and sends nothing — it does not even authenticate. The result then also carries:
  • status: "dry_run" and sent: false
  • would_send — the exact request that would have gone to AdvancedMD
Use it before any write you have not run before. AdvancedMD has no undo and no idempotency key. Read warnings when it appears. It means AdvancedMD returned a shape the catalog did not predict, and the data may be partial. This is surfaced rather than swallowed because a silently-empty result is indistinguishable from “this patient genuinely has no records”.

​
Limits and side effects

  • Writes are not idempotent and not retried. AdvancedMD has no idempotency key and, for most of these actions, no undo. Calling a write twice creates two records — two patients, two batches, or a patient who receives the same form twice.
  • Rate limiting is real. AdvancedMD returns HTTP 429 under modest concurrency; calls are paced and retried with backoff per office, so a burst of operations will take longer rather than fail.
  • Access differs per office. An operation that works for one AdvancedMD office can be unavailable on another belonging to the same customer. A failure on one office proves nothing about another.
  • Document upload lands a file on the patient’s timeline. It cannot attach to a visit or encounter, and there is no delete.

​
Expected errors

​
Available operations

Operations are grouped by surface: pm_* covers practice management (patients, scheduling, charges, master files) and ehr_* covers the clinical record and patient forms.

​
Patient-form reads

  • advancedmd_op_ehr_list_forms_for_review returns one row per patient (patientid, fullname, appointmentlist). Each appointment carries provprofid, apptid, apptdate, consentformlist and intakeformlist, and the forms are nested inside those lists, not flattened. A list holding a single entry can come back as a bare object, so treat one object as a one-item list. Paging counts patients: keep requesting page_num until a page returns fewer than page_size patients. Every body field is always sent; any you omit goes out with the defaults (period and status_filter All, expired 0, page_num 1, page_size 50, the other filters empty). A very large page can hit the 1 MB response limit; if it does, lower page_size.
  • advancedmd_op_ehr_get_patient_forms returns forms tied to an appointment and forms with no appointment in one combined list. matched_at names each container that was present.
  • advancedmd_op_ehr_get_consent_form returns the form’s consentformid, status, and the patient’s answers: checkboxlist.checkbox (ordinal, checked, where "1" means ticked) and fieldlist.field (ordinal, value). Both are always arrays, even with one entry. The ordinal is the answer’s position in the form, so read decisions from these lists rather than parsing the escaped HTML in form.

​
Insurance write-back

advancedmd_op_pm_update_insurance_copay and advancedmd_op_pm_update_insurance_deductible each change one thing on one insurance plan — the copay (always written as a dollar copay), or the deductible and deductible met — and leave the rest of the plan as it is. AdvancedMD’s updateinsurance takes each field twice: the value it has stored now (@o_<field>), which it checks before writing, and the value to store. So both tools take the plan’s current values as current_* inputs. Read the plan with advancedmd_op_pm_get_patient_insurances first and pass its values unchanged:
  • current_carrier and current_begin_date are required. Every other current_* field is optional, but pass each one the plan has.
  • A current_* field you omit is left out of the request, and AdvancedMD keeps its stored value.
  • A stale read fails instead of overwriting: AdvancedMD rejects a current_* value that no longer matches what it has stored.
A successful write returns success="1" in data. Treat any other value as a failed write, even when there is no error. These tools write whatever amount they are given. Deciding the amount is the agent’s job, and so is checking first. advancedmd_op_pm_list_patient_memos returns the memos on the patient’s record, including the display memos (type D) where staff leave instructions such as not to change a copay. advancedmd_op_pm_update_patient_employer sets the employer name on the patient. It is separate from advancedmd_op_pm_update_patient because that tool forces the change through AdvancedMD’s confirmation (@force=1), and the employer write does not.

​
Trying an operation locally

The catalog ships with a command that runs one operation through the same executor the tools use, so a result there is the result an agent would get. It needs no MCP client and no running platform.
Arguments are validated against the operation before anything is sent, so a typo is rejected locally rather than by AdvancedMD.

​
Verification status

Every read operation in this catalog except advancedmd_op_pm_list_patient_memos has been called against a live AdvancedMD test office and its response shape confirmed. The memo read’s response shape comes from a client already running it in production; its tool description says so. Write operations are verified by building and inspecting the exact request they would send, not by executing them: they alter real patient records. Where a write’s payload can be corroborated against a client already running it in production, that is recorded in the operation’s own guidance — the two form-accept operations and the decline are confirmed field-for-field against fleming’s implementation, which runs them on a schedule against a live tenant. The copay, deductible and employer writes copy fleming’s production requests field-for-field, and none of them has been sent to a live tenant from here. A handful of operations carry caveats in their own tool description — that an inner element name is inferred rather than observed, or that a request shape comes from a known-good client rather than a test call. Those notes are part of the tool description the agent sees, so they are visible where they matter.