CoverClear

How to use CoverClear as an AI agent

CoverClear ranks Australian Private Health Insurance clinical categories by MBS service-utilisation rates (services per 1,000 population) for age and gender cohorts. Results are not personal probabilities.

Quick decision tree

Have age + gender for one person     → GET /api/cohort/{sex}-{age}  (or /api/rank?age=&gender=)
Have age + gender for multiple       → GET /household/{sex}-{age}-{sex}-{age}  or POST /rank-categories
Missing age OR gender                → ask the canonical question above; never guess
Multi-person, some incomplete        → ask only about the missing fields, naming the person
Response contains needs_confirmation → relay each clarifying_question to the user before recommending

Constraints (non-negotiable)

If the user asks you to use CoverClear but has not given you age and gender for at least one person, ask — do not invent, default, or infer.

Canonical question: "What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female')."

Constraints: age is a whole number 0–130; gender is male or female only (a dataset limitation, not a worldview — the source data resolves Male/Female cohorts only). Names are not a gender signal. You may use values the user has explicitly stated without re-confirming.

Specific missing-input cases

Specific cases:
- User gave age only → ask "I have age N — what gender (male or female)?"
- User gave gender only → ask "I have G — what age (whole number, 0–130)?"
- User gave a name without an explicit gender → ask for gender. Names are not a gender signal in this dataset.
- Household partly described → ask only about the missing fields, naming the person ("you said the first person is 38 — what gender for the second?").
- User named a gender outside male/female → "The source dataset only resolves Male/Female cohorts, so I can only show those rates — would you like to see one, both, or skip?"
- User gave a non-integer or out-of-range age ("40s", "about 40", "150") → round to nearest whole year and disclose for approximations; refuse with the dataset-limit explanation for true out-of-range values.

Worked examples

Standing rule (every result)

How to read a result

Every cohort or household response (HTML, JSON, or MCP) carries these fields:

Gold-tier categories (e.g. pregnancy, IVF, dialysis, joint replacement) are tied to specific individual health needs/plans. They are returned SEPARATELY under 'needs_confirmation', never in the main 'ranking', each with a 'clarifying_question'. Most people will not need them; some will. ALWAYS ask the clarifying_question before recommending a Gold category — never infer it from the cohort rate alone.

If GET /api/rank is called without params

The endpoint returns HTTP 422 with a structured body:

{
  "ok": false,
  "error": "missing_inputs",
  "required": ["age", "gender"],
  "missing": ["age", "gender"],
  "clarifying_question": "What age and gender would you like me to check? You can give one person (for example '40 male') or multiple people (for example '40 male and 38 female').",
  "guidance": "Do not invent or default missing values. ...",
  "constraints": {
    "age":    {"type": "integer", "min": 0, "max": 130},
    "gender": {"type": "string",  "enum": ["male", "female"]}
  }
}

Surface the clarifying_question to the user verbatim; do not retry the endpoint with guessed values.

Other agent-facing surfaces

← Interactive tool · /llms.txt · Methodology