Lab Tests Tools

listAvailableLabTests

Lists lab tests purchasable in the user's confirmed US state. Lab availability and price are state-specific (NY/NJ have different catalogs than other states), so this tool requires a confirmed state and fails closed without it.

Parameter	Notes
confirmedUsState	Required. Two-letter US state code (e.g. "NY", "NJ", "FL"). The state must be confirmed with the user — never guess.
query	Free-text search by name or description
isPopular	"true" or "false"
loincSlug	Filter to tests including a specific marker

Fail-closed behavior

If confirmedUsState is missing or blank, the tool returns:

{
  "ok": false,
  "locationRequired": true,
  "tests": []
}

Do not retry with a guessed state. Ask the user to confirm their state, then call again.

Canonical identity

A lab's product identity is externalId + objectKey + provider + state scope + price — not its display name. Two results with the same name can be different sellable products across states or providers (e.g. a "Betterness Baseline" variant for NJ vs other states). Never dedupe by name and never assume two same-named items are interchangeable.

What you get back

Successful response:

{
  "ok": true,
  "locationRequired": false,
  "confirmedUsState": "NJ",
  "tests": [{
    "externalId": "...",
    "objectKey": "betterness-baseline-nj-bioreference",
    "name": "Betterness Baseline",
    "provider": "BioReference",
    "price": 199,
    "stateEligibility": {
      "eligible": true,
      "confirmedUsState": "NJ",
      "scope": "available_in",  // one of: "available_in" | "all_except" | "all"
      "availableIn": ["NJ"],
      "notAvailableIn": [...]
    },
    "includedBiomarkers": [{
      "name": "ApoB",
      "type": "BIOMARKER",
      "loincSlug": "apo-b"
    }]
  }]
}

Each test field:

• objectKey — canonical identity, needed for purchaseLabTest and purchaseLabTestWithCheckout
• externalId, name, description, provider, price, isPopular, imageUrl
• stateEligibility — why the lab is eligible. scope values: "all" (no restrictions), "available_in" (whitelist — only listed states), "all_except" (blacklist — all except listed states)
• includedBiomarkers — each marker has name, type (BIOMARKER or PANEL), and LOINC identifiers (loincSlug for BIOMARKER, loincSlugs for PANEL)

Pattern: gap-driven test recommendation

1. searchBiomarkers — see what the user has
2. getLoincCodes — find slugs for missing biomarkers
3. Confirm the user's US state if not already known
4. listAvailableLabTests(confirmedUsState, loincSlug) — find purchasable tests that include those slugs
5. Recommend by objectKey, price, and full marker list. Never reference labs by name alone.