What should the system prompt say?
Paste this block into your assistant’s system prompt and adapt the wording to your product, without removing any rule.How does the conversational questionnaire work?
1
Start
hidoctor_questionnaire_start with a category_slug (from
hidoctor_questionnaire_categories). Returns the first unanswered question
with answered_count and applicable_total, and resumes a questionnaire
that was already started.2
Answer, one question at a time
hidoctor_questionnaire_answer records one answer and returns the next
question. The server owns the branching, so you never evaluate conditions
yourself. Answers accumulate; the patient can stop and continue later with
hidoctor_questionnaire_current.3
Review and correct
hidoctor_questionnaire_review returns the answers as readable text.
hidoctor_questionnaire_back returns to an earlier question. If a changed
answer closes a branch, the response lists dropped_question_keys; tell the
patient when it matters.4
Submit
When the status is
ready_to_submit and the patient has confirmed, call
hidoctor_questionnaire_submit. It returns an approval_url: the patient
approves the submission on Hi Doctor, then you commit it. See
Approval links.Which answer formats should the assistant send?
Each question says how to answer it. Read itskind, and when a question
carries answer_instructions, follow them exactly. Always send the option
values the server returned, never the translated labels. Question text and
labels come back in the language of the patient’s profile, so ask in that
language.
The answer bodies (single and multiple choice, input fields, grid rows,
follow-ups, skips and batches) are the same as in the REST API and are
documented once, under
Send an answer in the
questionnaire guide. The connector-specific notes are on
Workflows.
A worked example: next actions
A good assistant turn names what happened and what comes next, and asks before anything consequential:How should the assistant handle errors?
Errors come back as tool results withisError: true and a structured
error object. The shape is stable; the message text below is illustrative:
code, message, retryable, field_errors, state,
next_action and correlation_id. Depending on the error, field, fields,
hint, status, missing_fields, current_period_end or
early_order_locked_until can also be present. Follow next_action rather
than retrying blindly, and quote correlation_id when contacting Hi Doctor.
Approval-link codes, such as
confirmation_expired or idempotency_conflict,
are listed on Approval links.
Handling long lists
List tools default to a concise summary of a page and reporthas_more and
next_offset. To count or sum, for example “how much have I paid this year”,
keep calling with offset set to next_offset until has_more is false. See
Lists and pagination.
Things that will bite you
The journal is offered with weight-loss treatment
The journal is offered with weight-loss treatment
Call
hidoctor_progress_status before offering to track anything. It says
whether the journal is enabled, needs an active subscription, or is
unavailable.Weight replaces by day; notes and injections append
Weight replaces by day; notes and injections append
Logging weight for a date replaces that day’s entry. Logging a note or an
injection twice creates two entries.
Reading the message thread does not create it
Reading the message thread does not create it
hidoctor_messages_get_thread reads the conversation without creating it.
If the patient has none yet, hidoctor_conversation_open creates it.Checking a checkout can complete it
Checking a checkout can complete it
hidoctor_checkout_status can finalise a paid session and create its
consultation. Call it when the patient says they have paid, not in a loop.Missing tools mean missing permissions
Missing tools mean missing permissions
If a tool is absent, the patient did not approve its permission. Say so
rather than looking for a workaround. See Permissions.
Without MCP
If your product calls Hi Doctor without a model in the loop, use the REST API. Keep REST credentials in your application; never place them in a prompt.Frequently asked questions
Does the system prompt make an assistant safe on its own?
No. A system prompt is guidance, not enforcement. Hi Doctor’s servers enforce permissions and clinical eligibility, but the assistant must still record only the patient’s own answers.Can the assistant suggest a medicine or a dose?
No. The assistant never gives medical advice, suggests a medicine or a dose. A doctor reviews every consultation and decides.When must the assistant ask the patient for an explicit yes?
Before anything with consequences: sending a message, submitting a questionnaire, preparing a checkout, cancelling or reactivating a plan, ordering a refill early, reporting a side effect or deleting journal entries. It says exactly what will happen first.Can the assistant approve an approval link itself?
No. Only the account owner, signed in on Hi Doctor, can approve. The assistant gives the link to the patient, waits, and commits only after the operation is approved.Should the assistant send option labels or option values?
Option values. Labels are translated into the patient’s language, while values stay stable, so the server only accepts the values it returned.What should the assistant do with an error?
Read the code and next_action, fix the input or ask the patient, and check the current state before repeating any write. Quote the correlation_id when contacting Hi Doctor.Next steps
Workflows
Common patient tasks, step by step.
Questionnaire guide
Answer formats, skips, batches and revisions.
HTTP chat integration
Run the questionnaire from your own chat backend.
Safety
Who decides on treatment, and how.