How do approval links fit into a task?
Several steps below use an approval link. The tool prepares the action, the patient approves it on Hi Doctor, and the assistant commits it with the same arguments, theconfirmation_id and an idempotency_key. Some actions can be
prepared but are completed on hi-doctor.ai instead; the
patient reference marks them Available on the
website. The states and safe retries are on Approval links.
Complete a consultation questionnaire
The server decides which question comes next, which branches apply and when the answers are complete. The assistant asks, records the patient’s own answers and never answers for them.1
Pick the category
hidoctor_questionnaire_categories lists the categories and their slugs,
for example weight-loss or hair-growth. Pass the slug as
category_slug on every call.2
Start or resume
hidoctor_questionnaire_start returns the first unanswered question with
its options and progress, and resumes a questionnaire that was already
started. hidoctor_questionnaire_current returns the current question
later without changing anything.3
Ask and save each answer
Ask the question as returned, in the patient’s language, and offer its
options. Send the patient’s own answer with
hidoctor_questionnaire_answer; it returns the next question. Repeat
until the result says the questionnaire is complete.4
Go back when something needs changing
hidoctor_questionnaire_back returns to an earlier question, grid item
or follow-up without changing any answer. Send the corrected answer with
hidoctor_questionnaire_answer. If a change closes a branch, the answers
that no longer apply are dropped and listed in the result.5
Review with the patient
hidoctor_questionnaire_review returns every answer as readable text,
plus any required item still missing. Read it back and ask the patient
to confirm.6
Submit through an approval link
hidoctor_questionnaire_submit prepares the submission and returns an
approval_url. The patient approves it on Hi Doctor. Poll
hidoctor_operation_get, then commit with the same arguments,
confirmation_id and an idempotency_key.submitted (sent to a
doctor for review), ineligible (a clinical result; never re-answer to change
it) or covered_by_active_plan (the patient’s plan already covers it).
Which answer formats does the questionnaire accept?
The MCP tools accept the same answer bodies as the REST questionnaire, so the shapes are documented once, in the questionnaire guide:
Two points are specific to the connector:
- Optional revision check.
expected_revisionis optional inhidoctor_questionnaire_answer. Without it, the tool uses the revision it has just read. Pass it from the previous result when the patient may also be editing on hi-doctor.ai. - Older categories. Skips, batches,
expected_revisionand single grid or follow-up answers need the guided questionnaire. A category that does not offer it returnsguided_api_required; answer one whole question at a time instead.
Pay for a consultation
Checkout is completed on hi-doctor.ai, not through the connector.hidoctor_checkout_create can prepare a checkout and show it for approval,
but its commit returns backend_atomicity_required. Tell the patient this
before they approve anything.
1
Confirm what the patient is requesting
Agree the treatment, dose and plan (
one_off or subscription) the
patient wants to request. The doctor decides whether it is appropriate.2
Send the patient to hi-doctor.ai
The patient signs in on hi-doctor.ai, reviews the treatment, plan and
amount, and pays on Stripe’s page. Card details are never entered in chat.
3
Optionally show the checkout first
If the patient wants to see the amount in the conversation,
hidoctor_checkout_create with treatment_id, dosage and plan
prepares it and returns an approval_url, or lists missing profile
fields. Committing it returns backend_atomicity_required, and nothing is
charged.4
Confirm the payment
After the patient pays,
hidoctor_consultations_list shows the new
consultation. If you hold a checkout session_id,
hidoctor_checkout_status reports whether it was paid. It can finalise a
paid session and create the consultation, so call it once, not in a loop.Get a prescription or invoice
hidoctor_prescriptions_listorhidoctor_payments_listto find the right record.hidoctor_prescription_pdforhidoctor_payment_invoicefor the document. The result is a link and metadata, never the PDF bytes. Itsdeliveryfield says how the link opens; asigned_redirectlink opens without signing in.- Treat the document as confidential: give it only to the patient, never repeat it in a shared place, and do not store it.
hidoctor_payment_credit_note returns the credit note the same
way. If a prescription expired or was lost,
hidoctor_prescription_request_reissue prepares a request to the medical
team; the request itself is completed on hi-doctor.ai. How prescriptions reach
a pharmacy is explained on How it works.
Message the medical team
1
Check for replies
hidoctor_messages_unread_summary shows whether there are unread
replies. hidoctor_messages_get_thread reads the conversation without
creating it or marking it read.2
Open the conversation if needed
If the patient has no conversation yet,
hidoctor_conversation_open
creates it, or reuses the existing one.3
Prepare the exact text
Agree the wording with the patient, then call
hidoctor_message_send
with content. It returns an approval_url.4
Approve and commit
The patient approves the exact text on Hi Doctor. Poll
hidoctor_operation_get, then commit with the same content,
confirmation_id and an idempotency_key. After a timeout, repeat the
commit with the same key; never prepare the message again.5
Mark as read
hidoctor_messages_mark_read marks the conversation as read once the
patient has seen the replies.How do I send a file to the medical team?
Upload the file first through the connector’s file upload, which returns afile_ref: a short reference to the uploaded file that tools accept instead
of the file’s bytes. Then prepare hidoctor_message_attachment_send with that
file_ref and an optional caption, and follow the same approval steps.
hidoctor_message_attachment_get returns an attachment as a link. File
uploads need an MCP client that supports them.
Keep the progress journal
Start withhidoctor_progress_status: it says whether the journal is enabled,
needs an active subscription, or is unavailable. The journal is offered with
weight-loss treatment.
To correct an entry, call
hidoctor_progress_day_get for the day; it returns
each entry’s ID for the update tools. Deleting an entry is completed on
hi-doctor.ai. The older names hidoctor_progress_injections_log and
hidoctor_progress_notes_add still run for now but are hidden from the tool
list; update saved prompts to the new names (see
Patient tools).
Manage a subscription
hidoctor_subscription_getshows each plan and the end of its current period.hidoctor_subscription_cancelprepares cancellation of one plan, bysubscription_id, for the end of the paid period, never immediately.hidoctor_subscription_reactivateundoes it before that date. Both use an approval link.hidoctor_subscription_billing_portalreturns a confidential Stripe link for card, plan and billing details.hidoctor_subscription_early_orderbrings the next refill forward. It creates the renewal consultation now, is allowed once per paid period and cannot be undone. Explain that and get an explicit yes before preparing it; the patient then approves it through the approval link.- When a renewal consultation is waiting for the patient’s choice,
hidoctor_renewal_getwithaction: "pending"shows it, andhidoctor_renewal_confirmprepares the patient’s choice for approval.
Report a side effect
hidoctor_adverse_event_report sends a suspected side effect to the clinical
team for review. Ask for each detail (medicine, what happened, severity, when
it started) instead of guessing. It is not an emergency channel: for severe or
sudden symptoms, tell the patient to contact their local emergency number. See
Safety.
Lists and pagination
List tools takelimit and offset and a detail mode:
When
has_more is true, call the same tool again with offset set to
next_offset, keeping the same filters and ordering, until has_more is
false. With detail: "full", keep raising offset by limit until count is
reached. To count or add up rows, for example “how much have I paid in total”,
page to the end before you add anything.
Results are also capped in size, in both modes. If a page is too large to
return whole, the server returns fewer rows with truncated: true, has_more
and a next_offset; it never cuts a row in half. A single record that does
not fit returns a result_too_large error: ask for a smaller limit.
Frequently asked questions
Can an assistant answer the questionnaire for the patient?
No. The assistant asks each question as returned and records only what the patient said. Hi Doctor’s servers cannot tell whether an answer came from the patient, so the assistant must never pick, infer or suggest an answer.What does an ineligible questionnaire result mean?
It is a clinical result, not an error. Explain it plainly and do not send different answers to change it. The patient can message the medical team with questions.Can a patient pay for a consultation through the connector?
No. Checkout is completed on hi-doctor.ai, and payment happens on Stripe’s page. The connector can show a prepared checkout for approval, but its commit returns backend_atomicity_required and nothing is charged.Why is a prescription or invoice not attached to the result?
Document tools return a link and metadata, never the PDF itself. Treat the link as confidential, give it only to the patient and do not store it.What happens if a commit times out?
Repeat the same commit with the same confirmation ID, arguments and idempotency key. Hi Doctor checks what happened and never runs the action twice. Never prepare the action again to escape a pending state.Why does logging a weight replace the earlier entry?
The journal keeps one weight per day, so logging a weight for a date replaces that day’s entry. Injections and notes work differently: each call adds a new entry.How do I get every row of a long list?
Call the same list tool again with offset set to next_offset until has_more is false. Page to the end before counting or adding anything up.Next steps
- Build on Hi Doctor with AI: the system prompt and rules an assistant must follow.
- Approval links: operation states, expiry and safe retries.
- Patient tools reference: every tool, its permission and its hints.
- Troubleshooting: fixes for sign-in, permission and tool errors.