A zero-argument connectivity check. Use it to verify the server is live
before running the shortage → alternatives → cascade-check chain.

Returns:
    HealthStatus: {
        "status": str,      # "ok" when healthy
        "server": str,      # "rx_shortage_mcp"
        "version": str,     # package version, e.g. "0.1.0"
        "next_step": str    # what to call next
    }

Queries the openFDA Drug Shortages dataset by generic name and aggregates the
NDC/package-level records into a single status summary. National-level data only —
it does NOT reflect a specific pharmacy's local/regional stock.

Use this twice in the workflow: (1) to confirm the original drug is short, and
(2) to re-check EACH candidate alternative — an alternative may itself be in
shortage (the "cascade" check that is the point of this server).

Args:
    drug_name: Generic/ingredient name (e.g. 'furosemide').

Returns:
    ShortageResult — drug, in_shortage (bool), overall_status ('Current' /
    'To Be Discontinued' / 'Resolved' / 'no_record'), statuses (list of
    {status, count}), record_count, last_updated (MM/DD/YYYY or null),
    therapeutic_categories, reasons, and next_step guidance.

This is the FIRST step of the workflow. It uses RxNorm's prescribable search
(exact-then-normalized), falling back to approximate matching for typos.

IMPORTANT: if `match_type` is 'approximate', the result is a best guess — present
the `candidates` to the user and confirm the intended drug before proceeding. Do
not silently assume the top candidate is correct.

Args:
    name: The drug name as the user typed it.

Returns:
    NormalizeResult — found (bool), rxcui, name (resolved RxNorm name), match_type
    ('exact' / 'approximate' / 'none'), candidates (ranked, for approximate matches),
    and next_step guidance.

A drug commonly maps to SEVERAL ATC-4 classes (a pure single-ingredient class plus
combination-product classes). This tool returns them ALL, each flagged
`is_combination`, sorted single-ingredient-first. YOU choose the class: normally the
single-ingredient class matching the drug's main therapeutic use. Pass its `class_id`
to rx_find_alternatives.

Args:
    drug_name: Drug/brand name (e.g. 'furosemide', 'Lipitor').

Returns:
    DrugClassResult — drug, classes (list of {class_id, class_name, class_type,
    is_combination}), count, and next_step guidance.

These are CANDIDATE alternatives for a licensed professional to evaluate — NOT a
substitution instruction. Same-class membership does NOT imply clinical
interchangeability (route, indication, contraindications, dosing, and equivalence are
not checked; some members may be withdrawn or combination products). Every response
carries a `disclaimer` that you MUST surface to the user.

After calling this, re-check EACH member's supply with rx_check_shortage to flag the
ones that are also short (the cascade check).

Args:
    class_id: ATC-4 class id (e.g. 'C03CA').

Returns:
    AlternativesResult — class_id, members (list of {rxcui, name, is_combination}),
    count, capped (bool), disclaimer (mandatory), and next_step guidance.