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 35 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 35.

​
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.

​
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.

​
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 has been called against a live AdvancedMD test office and its response shape confirmed. 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. 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.