Patient education

The patient education tool (ctx.PATIENT_EDUCATION) is a built-in tool available inside any loop. It searches MedlinePlus  — the US National Library of Medicine’s patient-facing health library — and returns up to three topics with a plain-language summary and a link.

Reach for it when your loop needs to explain what something is. A model asked to describe hypertension from memory will produce something plausible and unattributable; this gives you text you can quote and a URL you can cite.

What this tool is for

• Grounding an explanation of a condition, symptom, test, or treatment.
• Giving a member a link they can read themselves.
• Pairing with symptomRedFlags — check urgency first, then explain the symptom with grounded wording.

What this tool is not for

• Not diagnosis. Topics describe the condition, never the member. “Here’s what chest pain can mean” is fine; “you have angina” is not.
• Not a substitute for urgency routing. If the symptoms sound severe or time-sensitive, say so alongside the education — don’t let a calm encyclopedia entry bury the fact that something needs same-day care.
• Not medicine information. Use ctx.MEDICINE.lookupReference for a drug’s label.

Tool API

Must be called inside a step.do callback — ctx only exists there. See Step context.

type PatientEducationTopic = {
  title: string | null;
  url: string | null;
  /** The topic's full summary, truncated to ~900 characters. */
  summary: string | null;
  /** The search-result snippet, truncated to ~500 characters. */
  snippet: string | null;
  source: string | null;
};
 
type PatientEducationResult = {
  query: string;
  language: "en" | "es";
  topics: PatientEducationTopic[];
  error?: string;
  source: string;
  guidance?: string;
};
 
type PatientEducationTool = {
  search(input: {
    query: string;
    language?: "en" | "es";
  }): Promise<PatientEducationResult>;
};

MedlinePlus publishes topics in English and Spanish only, which is what language accepts. The search matches on topic title, so "high blood pressure" works well and a long free-text question works poorly — pass the condition, not the member’s sentence.

When MedlinePlus is unreachable the result carries error and an empty topics array rather than throwing, so a step that only wanted supporting prose won’t fail the run.

Example

import { Workflow } from "./loop";
 
export class EducationLoop extends Workflow {
  async run(
    event: HealthEvent<{ symptom: string; words: string }>,
    step: HealthStep,
  ) {
    // Urgency first — never let education stand in for triage.
    const triage = await step.do("Check red flags", async ({ ctx }) =>
      ctx.HEALTH_CALCULATOR.symptomRedFlags({
        symptom: event.body.symptom,
        memberWords: event.body.words,
      }),
    );
 
    if (triage.frame === "urgent") {
      const routing = await step.do("Route to care", async ({ ctx }) =>
        ctx.HEALTH_CALCULATOR.emergencyRouting({
          country: "South Africa",
          concern: "medical_emergency",
        }),
      );
      return {
        action: "escalate",
        redFlags: triage.redFlags,
        emergency: routing.emergency,
      };
    }
 
    const education = await step.do("Ground the explanation", async ({ ctx }) =>
      ctx.PATIENT_EDUCATION.search({ query: event.body.symptom }),
    );
 
    const topic = education.topics[0];
    return {
      action: "explain",
      frame: triage.frame,
      title: topic?.title ?? null,
      summary: topic?.summary ?? null,
      readMore: topic?.url ?? null,
    };
  }
}

PHI posture

The tool sends only the search term to MedlinePlus and reads no Ollie data. As with any reference lookup, the term itself may reveal what a member asked about — treat the step’s inputs and return value as part of the run’s data.

Source

MedlinePlus Web Service, National Library of Medicine. Public, no API key. The service returns XML, which the tool parses to the four fields above.