Prescribing tools

The prescribing flow uses four tools in order: patient to sync (find, create or update), prescription to draft/sign, order to draft/send, and orders to fetch the result. The first three can change records and are not ID-only fetch tools. You do not need to ask the agent for a draft before sending. Drafting and review are built into the flow. A separate prescription signing call is optional; Photon enforces signing requirements when the order is sent. The JSON examples below are tool arguments. Replace placeholder IDs with IDs returned by Photon.

patient

Sync a patient: find, create or update. First try to match an existing patient using context already available, such as name, date of birth or phone. Don’t ask the clinician to repeat known information or create a new record before attempting a match. To create a patient, first name, last name, date of birth and sex are required (demographic.name.first, demographic.name.last, demographic.dateOfBirth and demographic.sex). A phone number is required to send an order, but not to create the patient. You can start matching an existing patient with fewer details, as in this example:

{
  "demographic": {
    "name": { "first": "Paige", "last": "Turner" }
  }
}

Input	Use
`id`	The existing patient ID, once resolved. Include the fields you intend to update.
`demographic`	Known identity and contact information, including `name`, `dateOfBirth`, `sex`, `phone`, `email` and `address`.
`clinical`	Known allergies, medications and diagnoses, using the tool’s patch fields.

Inspect patient, candidates and changes.unapplied. If several candidates remain, use available context to resolve one or ask for the minimum distinguishing detail. Never guess or silently switch patients. Continue with the selected ID and resend intended fields that have not been applied. Record known clinical context before medication search when possible. Missing history is not confirmed absence. Set an allergy none value only when no known allergies have been confirmed. Don’t ask for a pharmacy during patient sync. Provider accounts cannot set the profile’s preferred pharmacy through this tool.

prescription

Draft prescriptions, with optional standalone signing. Search and progressively complete or update the draft. Start with a drug name or search string before asking for missing strength, dosage, instructions, quantity, units, days supply or refills.

{
  "patient": { "id": "pat_resolved" },
  "treatment": { "name": "amlodipine" }
}

Omit patient if identity is not yet available. This allows medication search; creating a patient prescription requires a resolved patient. Include any prescription details already supplied by the clinician.

Input	Use
`id`	A returned prescription ID to continue editing the same draft.
`patient.id`	The resolved patient, when available.
`treatment.name`	Drug name or search text for the initial call.
`treatment.id`	A medication ID from a returned choice.
`instructions`	Directions confirmed by the clinician.
`dispense`	`quantity`, `unit`, `daysSupply`, `refillsAllowed` and `dispenseAsWritten`, as needed.
`clinical`	Prescription diagnoses and notes.

Use returned choices in changes.unapplied to resolve the treatment and collect missing details. Resend pending inputs with the selected treatment ID, patient and any existing prescription ID. Calls do not retain unapplied inputs for you. Photon may populate draft directions or dispense details with defaults. Show them to the prescriber and confirm or correct them before signing or submitting. A medication match alone does not establish a complete clinical screen or coverage check; inspect returned screening and warnings.

Sign a reviewed prescription

Optional: use this when your workflow needs to sign a prescription separately from sending the order. It is an explicit call to the same prescription tool, separate from edits. After the prescriber approves the draft, copy its signing.contentHash into signing.signedHash:

{
  "id": "rx_draft",
  "signing": {
    "signedHash": "<signing.contentHash from the reviewed prescription>"
  }
}

Inspect the returned prescription.signing.state and unapplied changes before reporting success. Don’t replace the reviewed hash with a newer one without a new review. Signing does not submit an order. Machine tokens cannot sign.

order

Draft and send orders from existing prescriptions. As part of the send flow, add the drafts for the synced patient:

{
  "patient": { "id": "pat_resolved" },
  "prescriptions": { "add": [{ "id": "rx_draft" }] }
}

Input	Use
`id`	Continue an existing order.
`patient.id`	The resolved patient when preparing an order.
`prescriptions.add` / `prescriptions.remove`	Add or remove existing prescription references.
`pharmacy`	An explicitly requested destination for this order. Otherwise omit it.
`state`	`DRAFT` for preparation; `SUBMITTED` for explicit finalization of an existing order.

A call without an order ID may resume a matching draft. Review every prescription in the returned order, including any already present, plus combined screening and unapplied changes. Don’t ask for a pharmacy or make it a prerequisite for submission. Don’t infer a choice from a previous order, profile preference or shopping result. Photon handles the fulfillment link and fallback routing. See Pharmacy changes for an explicitly requested destination.

Submit the reviewed order

The patient must have a phone number before you send an order. If it is missing, update the existing patient with patient, using its ID and demographic.phone. After the prescriber approves the complete order, call order with only its ID and submission state:

{
  "id": "ord_prepared",
  "state": "SUBMITTED"
}

Photon enforces authorization and signing requirements. If it reports an unmet requirement, resolve that requirement against the existing records before continuing. Confirm the returned signing and order states before reporting success. Submission cannot be combined with content or pharmacy edits. Check order.state, each prescription’s signing state and changes.unapplied, then read back with orders. A DRAFT order has not been submitted. SUBMITTED does not by itself confirm pharmacy receipt.

Read the result and continue

Response	What to do
`patient`, `prescription` or `order`	Keep any returned record ID for subsequent calls. A record can exist even if some changes were rejected.
`candidates`	Resolve an ambiguous record using known context or a focused question.
`changes.applied`	Check what Photon accepted.
`changes.unapplied`	Resolve rejected or ambiguous fields; inspect `reason` and `options`.
`warnings`	Surface limitations, including unavailable history or screening.
`links.review`	Open the record in Prescribe when a review link is available.

If clinical context, prescription content, order membership or the destination changes, obtain a fresh review before finalization. Empty or unavailable screening does not establish that a complete check found no problems. For errors, follow userAction when present. An unknown write outcome means the operation may have completed. Preserve returned IDs and inspect the existing record before another write; do not automatically retry or create a replacement.

Network

GraphQL

MCP

Webhooks

Prescribing tools

patient

prescription

Sign a reviewed prescription

order

Submit the reviewed order

Read the result and continue

​patient

​prescription

​Sign a reviewed prescription

​order

​Submit the reviewed order

​Read the result and continue

patient

prescription

Sign a reviewed prescription

order

Submit the reviewed order

Read the result and continue