> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hi-doctor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build on Hi-Doctor with AI

> A ready-to-paste prompt, the conversational questionnaire protocol, and the rules an assistant must follow.

Hi-Doctor is designed to be driven by an AI assistant. The
[MCP connector](/mcp/connect) exposes a patient's whole care journey as tools,
including a questionnaire that can be completed as a conversation rather than a
form.

This page is for whoever is building that assistant.

## Paste this into your system prompt

<Tip>
  Copy this verbatim into the system prompt of any assistant connected to
  Hi-Doctor. It encodes the rules below so you do not have to restate them.
</Tip>

```text theme={null}
You have access to Hi-Doctor, an online medical service, through its MCP
connector. You are acting on behalf of a patient who has connected their own
account.

WHAT YOU CAN DO
- Complete a medical questionnaire with the patient, one question at a time.
- Get them a payment link for a consultation or treatment plan.
- Read their consultations, prescriptions, orders and payments.
- Send and read messages to and from their medical team.
- Track progress: log and correct weight, injections and daily notes.
- Manage their plan: cancel, reactivate, or open the billing portal.
- Pull a renewal forward (early order) — only with the payment permission.

HOW TO RUN A QUESTIONNAIRE
1. Call hidoctor_questionnaire_start with the category the patient wants.
2. Ask the patient the question exactly as it is returned. Do not rephrase
   clinical wording, and do not merge several questions into one.
3. Present the returned options as the choices. Send back the option's `value`,
   not the label you showed.
4. Call hidoctor_questionnaire_answer with their answer. It returns the next
   question. Repeat until status is "ready_to_submit".
5. Use hidoctor_questionnaire_review to read the answers back to the patient
   before submitting. Use hidoctor_questionnaire_back to change one.
6. Call hidoctor_questionnaire_submit.

RULES
- Never invent, assume or infer a medical answer. If the patient has not
  answered, ask again. "I don't know" is a real answer. If none of the options
  fits, read them out and let the PATIENT choose — never choose for them, and
  never narrow the list down on their behalf.
- Never give medical advice, and never suggest a medication or a dose. A
  registered doctor decides those after reviewing the questionnaire.
- If the questionnaire comes back ineligible, say so plainly and do not try
  other answers to get a different result.
- Before anything that costs money or cancels a plan, tell the patient exactly
  what will happen and get an explicit yes.
- Cancelling a plan takes effect at the end of the paid period, not
  immediately. Say that.
- An early order is IRREVERSIBLE: it creates the renewal consultation now and
  uses up the one early order allowed this period. Explain that and get an
  explicit yes before calling it.
- A prescription or invoice link is a medical document. Give it only to the
  patient. If the result says delivery is signed_redirect, the link opens
  WITHOUT signing in — never repeat it anywhere shared and do not store it.
- If the patient describes severe or sudden symptoms — chest pain, difficulty
  breathing, suicidal thoughts, a severe allergic reaction — stop and tell them
  to contact their local emergency number. Do not continue the questionnaire.
```

## The conversational questionnaire protocol

<Steps>
  <Step title="start">
    `hidoctor_questionnaire_start` with a `category_slug` (`weight-loss`,
    `hair-growth`, `sexual-health`, …). Returns the first unanswered question
    plus `answered_count` and `applicable_total` so you can show progress.

    If the patient already had a part-finished questionnaire, it resumes where
    they left off.
  </Step>

  <Step title="answer, repeatedly">
    `hidoctor_questionnaire_answer` records one answer and returns the **next**
    question. The server decides what comes next, so branching is handled for
    you — you never evaluate a condition yourself.

    Answers are merged, not replaced. Nothing is lost between calls, and the
    patient can stop and come back later.
  </Step>

  <Step title="review and correct">
    `hidoctor_questionnaire_review` returns every answer so far in readable
    form. `hidoctor_questionnaire_back` steps to the previous question so an
    answer can be changed.

    Changing an answer can close a branch. When that happens the response lists
    `dropped_question_keys` — answers that no longer apply and were removed.
    Mention it if it matters to the patient.
  </Step>

  <Step title="submit">
    `hidoctor_questionnaire_submit` returns an `outcome`:

    | Outcome                  | Meaning                                                       |
    | ------------------------ | ------------------------------------------------------------- |
    | `submitted`              | Sent for a doctor to review.                                  |
    | `ineligible`             | Clinically unsuitable. This is a normal result, not an error. |
    | `covered_by_active_plan` | Their existing plan already covers it.                        |
  </Step>
</Steps>

### Answer shapes

The question tells you how to answer it. Read `kind`:

| `kind`                      | Send                                                     |
| --------------------------- | -------------------------------------------------------- |
| `single`, `select`          | `value: "<option value>"`                                |
| `multi`, `multi-with-input` | `values: ["<option value>", …]`                          |
| `input`                     | `values: { "<field name>": <value>, … }`                 |
| `confirm`                   | `value: "understood"`                                    |
| `option-input`              | `option_inputs: { "<option_input_key>": "<free text>" }` |

Follow-up nodes carry an `answer_instructions` string saying exactly where the
value belongs. Follow it.

## The rules above are not technically enforced

Hi-Doctor cannot tell whether an answer came from the patient or was inferred
by the assistant. Nothing in the API validates that.

<Warning>
  The integrity of the clinical record depends on your assistant following the
  rules above. An assistant that fills in a plausible answer will submit
  successfully — and a doctor will prescribe from it. Treat "never invent an
  answer" as a hard constraint in your system prompt, not a suggestion.
</Warning>

What the server *does* enforce is eligibility.

## Eligibility is decided by the server

Contraindications, the BMI threshold, the age limit and the supported-country
check are enforced when the questionnaire is submitted — not by the assistant
and not by the website.

<Warning>
  Do not try to pre-screen a patient, and do not re-run a questionnaire with
  altered answers after an `ineligible` result. The check exists to keep people
  safe, and working around it would put a patient at risk.
</Warning>

## Things that will bite you

<AccordionGroup>
  <Accordion title="Send option values, not labels">
    Labels are human text and are translated into the patient's language.
    `value` is the stable identifier the server expects.
  </Accordion>

  <Accordion title="The questionnaire is in the patient's language">
    Question text comes back in the language on the patient's profile. Ask in
    that language.
  </Accordion>

  <Accordion title="Payment happens on Stripe, not in chat">
    `hidoctor_checkout_create` returns a link. Never ask for card details — you
    have no way to take them, and asking trains patients to hand card numbers
    to chatbots.
  </Accordion>

  <Accordion title="Progress tracking is weight-loss only">
    Every permission is granted on a normal patient connect, payment included.
    But the progress journal is built around weight, injections and an injection
    plan, so it is **only available on weight-loss treatment** — not on
    hair-growth or sexual-health plans.

    Call `hidoctor_progress_status` before offering to track anything. If a tool
    is missing entirely, the patient declined that permission at connect time —
    say so rather than guessing at a workaround.
  </Accordion>

  <Accordion title="Weight is one entry per day; notes and injections are not">
    Logging weight for a date replaces that day's entry. Notes and injections
    append, so logging twice creates two.
  </Accordion>
</AccordionGroup>

## Without MCP

If you are not using an MCP client, the same capabilities are available over
the [REST API](/api-reference/introduction) — including
[programmatic signup](/api-reference/signup) so a chat interface can create the
account too.