state_expert

What it answers

1. 1The callable STATE EXPERT — the data-availability + regulation X-ray for a US state.
2. 2Given a 2-letter state code (e.g. 'CT'), returns: (1) DATA AVAILABILITY — how many hospitals are priced, total price rows, distinct billing codes, care sites mapped, and payers with resolved coverage;
3. 3(2) the REGULATION object — the rules of the game in that state (transparency regime, required disclosures, public datasets like an APCD or rate-setting authority, and the completeness bar); and (3) the computed GAPS — required-or-known datasets we have NOT yet ingested (e.g. a mandatory APCD), so absence is reported as gap-vs-expected, not silently.
4. 4This is the 'what data do we have in this state, what is required here, and what is missing' entry a higher-level agent or operator reasons over.
5. 5Because hospital pricing is a NATIONAL substrate, a state can show many hospitals priced even before its county map is built (e.g.
6. 6MD).
7. 7Stateless + state-parameterized: one runtime serves every state.
8. 8To price a code across the state's hospitals, call compare_hospital_rates.
9. 9SOURCE: curated hospital chargemaster + care-site registry + the state-regulation object.
10. 10KNOWLEDGE (1.2.0): every answer lists the state's Marketplace and Medicaid knowledge pages (the States lane's per-state pages: regulators, what the state publishes, the rules, the plans) with their sections; pass page='marketplace' or 'medicaid' (and optionally section='<heading text>') to read one.
11. 11Pages exist for states hospital rules do not yet cover, so a found=false answer can still carry them.

Inputs (3)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
state_expert(state_code="CT")

curl -X POST https://api.vladahealth.com/v1/tools/state_expert \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state_code":"CT"}'

# the schema, no key
curl https://api.vladahealth.com/v1/tools/state_expert/schema

A real answer

{
 "value": {
  "state_code": "CT",
  "state_name": "Connecticut",
  "found": true,
  "fips": "09",
  "data_availability": {
   "hospitals_priced": 39,
   "hospital_price_rows": 42731575,
   "distinct_billing_codes": 110242,
   "care_sites_mapped": 19400,
   "care_sites_verified": 441,
   "payers_with_coverage": 36
  },
  "regulation": {
   "transparency_regime": "state-plus",
   "required_disclosures": [
    {
     "name": "hospital_hpt",
     "authority": "federal CMS HPT rule"
    },
    {
     "name": "payer_tic",
     "authority": "federal TiC rule"
    }
   ],
   "public_datasets": [
    {
     "name": "CT APCD",
     "kind": "all_payer_claims_database",
     "status": "mandatory",
     "ingested": false,
     "note": "CT runs a mandatory APCD (CT Office of Health Strategy) \u2014 richer than MRFs; not yet ingested = known gap"
    },
    {
     "name": "CT DOI rate filings",
     "kind": "doi_rate_filings",
     "status": "public",
     "ingested": false
    },
    {
     "name": "CHIME / hospital reporting",
     "kind": "state_hospital_reports",
     "status": "public",
     "ingested": false
    }
   ],
   "apcd_status": "mandatory",
   "completeness_bar": "all CT acute hospitals priced (HPT) + dominant carriers built (TiC) + APCD ingested for the claims-grounded layer",
   "source_urls": [
    "https://portal.ct.gov/ohs"
   ],
   "reviewed_by": "seed_2026-06-21"
  },
  "gaps": [
   {
    "item": "CT APCD",
    "kind": "all_payer_claims_database",
    "severity": "known_gap",
    "detail": "CT runs a mandatory APCD (CT Office of Health Strategy) \u2014 richer than MRFs; not yet ingested = known gap"
   },
   {
    "item": "CT DOI rate filings",
    "kind": "doi_rate_filings",
    "severity": "known_gap",
    "detail": "exists but not ingested"
   },
   {
    "item": "CHIME / hospital reporting",
    "kind": "state_hospital_reports",
    "severity": "known_gap",
    "detail": "exists but not ingested"
   }
  ],
  "freshness": {
   "last_verified_at": null,
   "status": "not_yet_tracked"
  },
  "caveats": [],
  "knowledge": {
   "marketplace": {
    "available": false
   },
   "medicaid": {
    "available": false
   }
  }
 },
 "unit": "profile",
 "vintage": "as_built",
 "source": {
  "dataset": "Hospital Price Transparency machine-readable standard-charges files",
  "publisher": "cms",
  "catalog_updated_at": "2026-05-28"
 },
 "caveats": [],
 "response_hash": "bed64dbd8b60f5de3455aa9f93d25a598e89bd7b2f0600d06b24c767a2ae8bea",
 "semantic_version": 1,
 "tool_version": "1.2.1",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "profile",
  "scope": {
   "tool": "state_expert",
   "filters": {
    "state_code": "CT"
   }
  }
 },
 "method": "Computed over the filters shown in this answer's scope, from the sources listed in its evidence. Nothing outside those filters was included.",
 "evidence": {
  "sources": [
   {
    "dataset": "Hospital Price Transparency machine-readable standard-charges files",
    "publisher": "cms",
    "catalog_updated_at": "2026-05-28"
   }
  ],
  "response_hash": "bed64dbd8b60f5de3455aa9f93d25a598e89bd7b2f0600d06b24c767a2ae8bea"
 }
}

What comes back

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "description": "value carries {state_name, fips, data_availability{hospitals_priced,\nhospital_price_rows, distinct_billing_codes, care_sites_mapped,\npayers_with_coverage}, regulation{...}, gaps[], freshness{...},\nknowledge{marketplace, medicaid}, and with page: knowledge_page{text, ...}}.",
 "properties": {
  "value": {
   "default": null,
   "title": "Value"
  },
  "unit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Unit"
  },
  "vintage": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Vintage"
  },
  "source": {
   "$ref": "#/$defs/Source"
  },
  "methodology": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Methodology"
  },
  "quality": {
   "$ref": "#/$defs/Quality"
  },
  "invariants_applied": {
   "items": {
    "type": "string"
   },
   "title": "Invariants Applied",
   "type": "array"
  },
  "caveats": {
   "items": {
    "type": "string"
   },
   "title": "Caveats",
   "type": "array"
  },
  "response_hash": {
   "default": "",
   "title": "Response Hash",
   "type": "string"
  },
  "semantic_version": {
   "default": 1,
   "title": "Semantic Version",
   "type": "integer"
  },
  "tool_version": {
   "default": "unknown",
   "title": "Tool Version",
   "type": "string"
  },
  "explanation": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Explanation"
  },
  "status": {
   "default": "complete",
   "title": "Status",
   "type": "string"
  },
  "refusal": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Refusal"
  },
  "failure": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Failure"
  },
  "as_of": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "As Of"
  },
  "freshness_state": {
   "default": "unknown",
   "title": "Freshness State",
   "type": "string"
  }
 },
 "title": "StateExpertResponse",
 "type": "object"
}

Sources

Known limits (3)

1. 1regulation_object_is_seed_not_yet_dim_state_regulation
2. 2freshness_not_yet_tracked_pending_refresh_cascade
3. 3county_map_built_for_CT_only