{"tools":[{"name":"certified_measure","version":"1.0.0","description":"Run a GOVERNED KPI by name from the certified measures registry. A measure is a registry entry (definition + vintage bindings + official citation + canonical SQL); this tool runs ONLY that registry SQL, so a governed statistic (like the enrollment-weighted share of MA-PD enrollees in 4-plus star contracts) is computed by a compiled methodology, never an improvised join. Call with NO name to list every measure with its status and definition. Call with a name (and optionally rating_year, an int) to execute that measure and get the rows plus the vintage columns, the official citation, the certification status (draft / certified), and the definitional notes. Use this for any governed KPI FIRST; if no measure covers the question, fall back to query_substrate and label the result uncertified.","layer":"L2","input_schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"rating_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Rating Year"}},"title":"CertifiedMeasureInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["Runs ONLY the registry's canonical SQL; a governed question with no matching certified measure is NOT answered here, and there is currently NO sanctioned raw-SQL fallback (query_substrate is quarantined pending its truncation-honesty re-grade). An unanswered governed question stays unanswered rather than improvised.","A measure with status 'draft' has not yet been certified by the owner; treat its number as provisional until status is 'certified'."],"parameter_schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"rating_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Rating Year"}},"title":"CertifiedMeasureInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"CertifiedMeasureResponse","type":"object"},"title":"Certified Measure","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"compare_hospital_rates","version":"1.22.0","description":"NEGOTIATED RATES BY INSURER AND PLAN ARE SERVED HERE: hospital price-transparency files carry the rate each hospital filed for each payer and plan (the insurer-file / TiC tools are coming soon). Compares what a billing code costs ACROSS hospitals (cheapest real price first) with a p10/median/p90 benchmark AND a per-(payer x line-of-business) breakdown. The product query for 'where is care cheapest' and 'what does each payer actually pay'. Reads the canonical serving view `vlada_curated.vw_fact_hospital_chargemaster_canonical`, which resolves each raw payer string to its REAL parent entity (the canonical payer graph) and classifies each plan to a regulatory line-of-business (commercial / medicare_advantage / medicaid / marketplace / ...). Inputs: billing_code (required), state (optional 2-letter), code_system (optional), billing_class (default 'institutional' = facility/UB-04; or 'professional'/'both'; classes are never mixed -- since 1.6.0 'institutional'/'professional' each WIDEN to include billing_class_resolved='both' rows, a charge posted on both the facility and professional side of a bill per the HPT schema; pass 'institutional_only'/'professional_only' for the strict single-class stratum), limit (default 25), payer (optional brand OR parent, e.g. 'Aetna' or 'CVS Health'), line_of_business (optional, e.g. 'medicare_advantage'; `all_products` is one rate a hospital posts for all of a payer's products, and it is never in the commercial default). Each returned rate carries the view's canonical payer columns (`payer_canonical_id`, `payer_parent_name`, `payer_entity_class`, `payer_match_method`) plus `line_of_business` so a comparison is apples-to-apples (Aetna-MA != Aetna-Commercial). `value.by_payer_lob` is the 'rates across all the payers' table. CROSS-SUBSTRATE: every rate also carries x_medicare (the multiple of the Medicare allowed amount: PFS national non-facility for professional, OPPS APC for outpatient institutional, IPPS MS-DRG national base for inpatient DRG codes); `value.medicare` holds the allowed amount + schedule + year, so the answer is 'this payer pays 1.6x Medicare at this hospital'. VALIDATION (load-bearing): billing_class is normalized + inferred from code_system/rate_type where the source omits it; only the requested class is compared; class-implausible rates (e.g. $0.007 for a CT) and code-relative outliers are filtered. CHEAPEST HEADLINE (1.2.0): `value.cheapest` is ranked over rows PLAUSIBLE for the code's Medicare basis -- when the allowed amount is a real procedure (>= $500) a row under 0.3x Medicare (the comparability cascade's own lower sane bound) is set aside into `value.implausible_tail` (full rows + floor + reason, never deleted; benchmark still includes it), and the rest rank hospital-stated methodology (fee_schedule/case_rate/per_diem) before methodology-unknown, rate ascending within each tier -- read `plausibility` + `rank_tier` on each row. Under the $500 gate (imaging / visits / labs) only the placeholder floor below applies, so a $44 head CT still headlines. CASE-RATE HEADLINE (1.7.0): on a DRG/case-rate seat the floor is 0.5x (not 0.3x -- an inpatient rate below half of IPPS is not credible as the full case price), and `cheapest` headlines hospital-STATED case_rate rows ONLY when at least one survives the floor; methodology-unknown rows are demoted into `value.implausible_tail` (tail_reason='methodology_unknown_demoted') even when they themselves clear the floor. `cheapest` headlines an unknown row only when NO stated row survives, and a `headline_methodology_unknown` warning caveat says so. ENCOUNTER-BASIS FLOOR (1.15.0): the floor also reads the Medicare basis -- when the allowed amount is a facility-encounter payment (OPPS APC, IPPS MS-DRG, ASC; e.g. the comprehensive APC behind a CPT 27447 knee) the floor is 0.5x on every seat except per_diem, stated as `floor_rule='encounter_basis'` on every floor block and on value.implausible_tail. ONE CODE SYSTEM PER WINDOW (1.3.0): `cheapest` holds rows of the seated code system only (`value.code_system_resolved`, the dominant system or the caller's `code_system`), each row stamped `code_system`; when the floor empties a full window the tool re-asks once for rows at or above the floor rate (`value.cheapest_window.second_pass`), and if `cheapest` still ends empty a `no_plausible_rows_in_window` caveat says why. ONE METHODOLOGY FAMILY PER WINDOW (1.4.0): within the seated code system, `cheapest` and the re-seated `value.benchmark` / `comparable_benchmark` are further restricted to ONE methodology family -- fee_schedule (a line, the natural family for CPT/HCPCS/APC/RC), case_rate (an admission, the natural family for a DRG/MS-DRG seat), or per_diem (a day) -- because a case rate, a per diem and a fee schedule price different economic objects and must never share a median or a ranked list. `methodology_family` (optional: fee_schedule|case_rate|per_diem) overrides the natural seat. Rows the hospital stated in a DIFFERENT family are set aside into `value.other_family`, in full, never blended in; `value.by_methodology_family` reports n/n_hospitals/p10/median/p90 for every family present, and a `methodology_families_mixed` caveat fires when more than 10% of the population sits outside the seated family. BY_METHODOLOGY RECONCILES (1.6.1): `value.by_methodology` (percent_of_charge/fee_schedule/case_rate/per_diem/other/unknown, with median_rate_over_gross_charge) is narrowed to the SAME population `value.benchmark.n` reports -- sum(by_methodology[].n) == benchmark.n, ALWAYS, by construction; the unstratified, every-family view (within the seated code system) is `value.by_methodology_all_families`, which is what `value.percent_of_charge_share` and the `methodology_mix` caveat read (percent_of_charge rows are always 'unknown' family and would otherwise be invisible once a family is seated). SOURCE: CMS Hospital Price Transparency MRFs (45 CFR 180.50) + CMS Medicare PFS/OPPS fee schedules. KNOWN GAPS: not geo-aware beyond state; payer resolution covers ~80.9% of volume and line-of-business ~85.7% (measured on the 70553 probe, 2026-08-13; call state_expert for live per-state counts), unmatched rates fall to '(unresolved)'/'unspecified'; bare Blue-family labels (e.g. 'Bcbs') keep the Blue company the hospital's state or county identifies (the state's one licensee, or the county's Blue in a split state); with no such evidence they are bucketed '(blue family: label too generic to attribute)' with payer_resolution='generic_label' and never attributed to a specific Blue parent; IPPS DRG x_medicare is the national base (excludes wage index/IME/DSH/outliers); x_medicare null for revenue/non-HCPCS CDM codes; ghost-rate filter is heuristic. DRG GROUPER PRECISION: MS-DRG, APR-DRG and AP-DRG are different maintainers with different numbering (MS-DRG 470 = joint replacement, APR-DRG 470 = chronic kidney disease) and only MS-DRG prices against the IPPS base. Served data is split into MS_DRG / APR_DRG / TRIS_DRG / ... (code_system_precision 'token' or 'shape_inferred'), so an MS_DRG seat is `value.medicare.precision` 'exact' and the other groupers carry no Medicare basis; only a row still on the transitional bare 'DRG' string reads 'drg_grouper_unknown'. CODE-SYSTEM SPELLINGS (1.18.0): code_system is folded to the served bucket before anything runs ('MS-DRG' / 'ms_drg' / 'msdrg' -> 'MS_DRG', 'APR-DRG' -> 'APR_DRG', 'hcpcs' -> 'HCPCS_II', 'cpt-4' -> 'CPT'; a bare 'DRG' is not guessed), and code_system naming the cell's natural seat is served from the precomputed table. PAYER FROM THE TABLE (1.18.0): payer naming ONE parent company (the parent name, or a brand it owns: Aetna -> CVS Health, UHC -> UnitedHealth Group, Anthem -> Elevance Health) is read from the table's payer level -- the headline is that parent's seated-family rows; value.served_from.payer_scope names the match; by_methodology and comparable_benchmark are not in the table per payer and say so in value.sections_unavailable. `by_payer_lob` lists the seated methodology family first; `value.by_payer_lob_cut` and each tail's `rows_cut_note` say where a list was cut. PLACEHOLDER TAIL (1.18.0; from a $100 basis since 1.20.0): under the $500 gate, a rate under 0.25x a $100-$500 Medicare basis (a $50 ED visit at 0.12x, a $32 brain MRI at 0.13x) leaves the ranked `cheapest` list for value.implausible_tail (tail_reason='below_low_basis_floor'); the medians still include it until the table is rebuilt. NO HEADLINE WITHOUT ITS FLOOR (1.22.0): when the seat or the Medicare part misses the budget, `cheapest` is withheld (value.cheapest_empty rule 'seat_unavailable', status partial, retryable) and the window's rows are in value.cheapest_unassessed, unranked. BOTH-CLASS DEFAULT STRATUM (1.6.0): billing_class 'institutional'/'professional' each widen to include billing_class_resolved='both' rows (a charge the HPT schema posts for both sides of a bill); every row still carries its own resolved `billing_class`, and a `both_class_rows_included` caveat states the measured count whenever the answer includes at least one such row. Measured on CT (2026-08-18): 9.63% of REAL_NEGOTIATED rows are 'both', 100% with no institutional sibling row -- previously invisible at the old strict-institutional default. Pass 'institutional_only'/'professional_only' for the pre-1.6.0 strict single-class stratum.","layer":"L2","input_schema":{"description":"Input contract for compare_hospital_rates.\n\n`billing_code` (required): the code to compare (CPT/HCPCS/DRG/RC/CDM...).\n`state`: optional 2-letter filter (e.g. \"FL\"). Omit for national.\n`code_system`: optional disambiguator when the same code exists under\n    multiple systems.\n`billing_class`: which class to compare; default \"institutional\"\n    (facility / UB-04). Classes are NEVER mixed; \"unknown\" is rejected.\n    Since 1.6.0, \"institutional\"/\"professional\" each WIDEN to include\n    billing_class_resolved='both' rows (a charge posted on both the\n    facility and professional side of a bill, per the HPT schema); pass\n    \"institutional_only\" / \"professional_only\" for the strict\n    single-class stratum (no 'both' rows).\n`limit`: max cheapest rows to return (1-200, default 25).\n`methodology_family`: optional override of the methodology family the\n    cheapest window + benchmark are seated on -- fee_schedule (a line) /\n    case_rate (an admission) / per_diem (a day). Defaults to the\n    NATURAL family of the seated code system (fee_schedule for\n    CPT/HCPCS/APC/RC, case_rate for a DRG/MS-DRG seat).","properties":{"billing_code":{"title":"Billing Code","type":"string"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"code_system":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Code System"},"billing_class":{"default":"institutional","title":"Billing Class","type":"string"},"limit":{"default":25,"title":"Limit","type":"integer"},"payer":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Payer"},"line_of_business":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Line Of Business"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"comparable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Comparable"},"facility_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Facility Type"},"methodology_family":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology Family"}},"required":["billing_code"],"title":"CompareHospitalRatesInput","type":"object"},"invariants":["hospital_billing_class_comparability_v1"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_hospital_comparison_mart","vlada_curated.vw_fact_hospital_chargemaster_comparable","vlada_curated.vw_fact_hospital_chargemaster_canonical","vlada_curated.vw_medicare_benchmark"],"semantic_views_used":[],"known_gaps":["hospital_billing_class_inferred","hospital_geo_state_only","hospital_ghost_rate_filter_heuristic"],"parameter_schema":{"description":"Input contract for compare_hospital_rates.\n\n`billing_code` (required): the code to compare (CPT/HCPCS/DRG/RC/CDM...).\n`state`: optional 2-letter filter (e.g. \"FL\"). Omit for national.\n`code_system`: optional disambiguator when the same code exists under\n    multiple systems.\n`billing_class`: which class to compare; default \"institutional\"\n    (facility / UB-04). Classes are NEVER mixed; \"unknown\" is rejected.\n    Since 1.6.0, \"institutional\"/\"professional\" each WIDEN to include\n    billing_class_resolved='both' rows (a charge posted on both the\n    facility and professional side of a bill, per the HPT schema); pass\n    \"institutional_only\" / \"professional_only\" for the strict\n    single-class stratum (no 'both' rows).\n`limit`: max cheapest rows to return (1-200, default 25).\n`methodology_family`: optional override of the methodology family the\n    cheapest window + benchmark are seated on -- fee_schedule (a line) /\n    case_rate (an admission) / per_diem (a day). Defaults to the\n    NATURAL family of the seated code system (fee_schedule for\n    CPT/HCPCS/APC/RC, case_rate for a DRG/MS-DRG seat).","properties":{"billing_code":{"title":"Billing Code","type":"string"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"code_system":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Code System"},"billing_class":{"default":"institutional","title":"Billing Class","type":"string"},"limit":{"default":25,"title":"Limit","type":"integer"},"payer":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Payer"},"line_of_business":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Line Of Business"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"comparable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Comparable"},"facility_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Facility Type"},"methodology_family":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology Family"}},"required":["billing_code"],"title":"CompareHospitalRatesInput","type":"object"},"output_schema":{"$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.0,"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 {billing_code, state, billing_class, cheapest[], benchmark}.","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":"CompareHospitalRatesResponse","type":"object"},"title":"Compare Hospital Rates","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"describe_data_source","version":"1.3.0","description":"Return the catalog record for one substrate data source. Compact by default (grain, queryable, claim ceiling, freshness SLA, top caveats, recommended next action, columns); pass verbosity='full' for the previous full record: description, row count, provenance chain reference, context doc path, known gaps, and the full source_product_card. IDENTIFIERS: accepts the PUBLIC source_code that find_data_sources returns (e.g. cms_ma_plan_payment) as well as a table FQN (e.g. vlada_curated.fact_rate) or a catalog source_id -- all three resolve to the same card. Also accepts a data-point ID, returning its exact bound table plus the selected point's units, grain, nulls and execution route. When the card includes a coverage-check recipe, run its stated query to inspect retained editions; it is not measured coverage. Do not infer all-history coverage from current-only rows. Avoid extra schema calls when this card already supplies the needed columns. A RETIRED source answers with a redirect (status retired + superseded_by + the successor's fqn), never a card. COLUMNS (1.1.0): the card's `columns` field lists each column's name and type (and a one-line note where the source publishes one), read from a committed snapshot -- never a live Glue call -- so a caller no longer has to `SELECT * LIMIT n` on query_substrate just to learn a table's shape. A source not yet in the snapshot reads `columns_unavailable: run snapshot` rather than silently omitting the field; run ops/scripts/snapshot_catalog_columns.py to populate it. WHAT TO QUERY (2026-09-18): every card carries a block saying what to type. It states the literal fully-qualified table name the raw SQL door accepts -- neither the public source code nor the catalog source id is a table -- plus the predicates a correct read carries (a currentness filter, a year pin, a partition column), and one bounded example SELECT that has been run through the door's own SQL guard before it was printed. A source served by a typed tool instead names that tool and its call; a seat not entitled to the table is told which pack grants it. Column lists are split: the data columns first, the row-lineage columns every row carries in their own named group.","layer":"L1","input_schema":{"properties":{"source_fqn":{"title":"Source Fqn","type":"string"},"verbosity":{"default":"compact","enum":["compact","full"],"title":"Verbosity","type":"string"}},"required":["source_fqn"],"title":"DescribeDataSourceInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"properties":{"source_fqn":{"title":"Source Fqn","type":"string"},"verbosity":{"default":"compact","enum":["compact","full"],"title":"Verbosity","type":"string"}},"required":["source_fqn"],"title":"DescribeDataSourceInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"CatalogResponse","type":"object"},"title":"Describe Data Source","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"describe_entity","version":"2.0.0","description":"Everything layer one holds about one entity (an entity_id from resolve_entity): what it is and its identifiers; who owned or controlled it on a date (on=YYYY-MM-DD, default today), the path to the top parent with each hop's basis, grade, dates and evidence; what it holds (contracts, plans, Medicaid plans, issuers, subsidiaries), or everything under its top parent with scope=group; its dated corporate events (acquisitions, mergers, transfers of business, renames) with filings. Every date follows the doctrine (at least since; last seen).","layer":"L2","input_schema":{"properties":{"entity_id":{"title":"Entity Id","type":"string"},"on":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"On"},"scope":{"default":"entity","title":"Scope","type":"string"},"events":{"default":true,"title":"Events","type":"boolean"},"limit":{"default":200,"title":"Limit","type":"integer"}},"required":["entity_id"],"title":"DescribeEntityInput","type":"object"},"invariants":["no_match_without_evidence","every_link_dated_and_sourced","observation_end_is_not_control_end","candidate_and_refuted_never_served"],"underlying_silver_tables_for_pinning":["vlada_ontology.l1_entity","vlada_ontology.l1_identifier","vlada_ontology.l1_edge","vlada_ontology.l1_evidence","vlada_ontology.l1_event"],"semantic_views_used":["vlada_ontology.l1_entity","vlada_ontology.l1_identifier","vlada_ontology.l1_edge","vlada_ontology.l1_evidence","vlada_ontology.l1_event"],"known_gaps":["Layer one only: no facilities, doctors, networks or PBMs (layers two to five follow on Ben's signature).","About 16% of Medicare Advantage members sit under a chain with one hop resting on CMS's parent string alone (grade B); the top parent is not in doubt, the corroborating filing is not yet attached.","Belief time (what an earlier build served) is not yet queryable; every answer carries the build it was read from.","The 233 open review-queue rows (candidate contract transfers) are not served."],"parameter_schema":{"properties":{"entity_id":{"title":"Entity Id","type":"string"},"on":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"On"},"scope":{"default":"entity","title":"Scope","type":"string"},"events":{"default":true,"title":"Events","type":"boolean"},"limit":{"default":200,"title":"Limit","type":"integer"}},"required":["entity_id"],"title":"DescribeEntityInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"DescribeEntityResponse","type":"object"},"title":"Describe Entity","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"describe_schema","version":"1.0.0","description":"Return the semantic layer: marts, columns, invariants, canonical payers, and the tools YOU can call (the same list tools/list returns for you, never a wider catalog). Compact by default (a manifest: marts + a name + one-line summary per tool, under ~8K chars). Fetch one section with describe_schema(section='<mart>') / section='tools' / section='invariants'. Pass verbosity='full' for the previous full payload. Agents call this first to learn the surface, then fetch the section or tool they need.","layer":"L1","input_schema":{"properties":{"mart_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mart Name"},"section":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Section"},"verbosity":{"default":"compact","enum":["compact","full"],"title":"Verbosity","type":"string"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit"},"offset":{"default":0,"title":"Offset","type":"integer"},"include_invariants":{"default":true,"title":"Include Invariants","type":"boolean"},"include_examples":{"default":true,"title":"Include Examples","type":"boolean"}},"title":"DescribeSchemaInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"properties":{"mart_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mart Name"},"section":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Section"},"verbosity":{"default":"compact","enum":["compact","full"],"title":"Verbosity","type":"string"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit"},"offset":{"default":0,"title":"Offset","type":"integer"},"include_invariants":{"default":true,"title":"Include Invariants","type":"boolean"},"include_examples":{"default":true,"title":"Include Examples","type":"boolean"}},"title":"DescribeSchemaInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"SchemaResponse","type":"object"},"title":"Describe Schema","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"fetch_query","version":"1.0.0","description":"Fetch the result of an async job once it is done. Returns the wrapped tool's full response when status is done; a not_ready caveat while it is still queued/running; or the error when it failed.","layer":"L2","input_schema":{"properties":{"job_id":{"title":"Job Id","type":"string"}},"required":["job_id"],"title":"JobIdInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"properties":{"job_id":{"title":"Job Id","type":"string"}},"required":["job_id"],"title":"JobIdInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"AsyncJobResponse","type":"object"},"title":"Fetch Query","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"find_data_sources","version":"1.0.0","description":"Search the Vlada substrate catalog by keyword. Returns the matching data sources (commercial TiC, hospital HPT, Medicare, drug pricing, provider identity, curated marts, provenance registries) ranked by relevance. Compact by default (identity + queryable + claim ceiling + the exact describe_data_source call per hit); pass verbosity='full' for the previous full source_product_card per result. Paginates with limit (default 25, max 200) + offset; the response carries total_count, returned_count, and offset. Optional filters: {domain, stage, status, limit}. Agents call this first to discover what data Vlada has. Since 2026-09-02 the answer leads with DATA POINTS (`data_points`: the measure/dimension asked for, with its source, door, table.column and must-read trap) and the table cards follow as physical locations. Every hit carries `source_code` -- the one public code, which describe_data_source accepts verbatim -- alongside the table's `source_fqn`. Points and tables are ranked by ONE ranker (the authored data-point scorer). Retired tables are never returned; they appear only as `supersedes` on the live successor's card. BOUNDED (2026-09-18): the default call is compact and paged -- both the table cards and the data points come back a page at a time, each with its own total and next offset -- so a default call can never truncate. Pass verbosity='full' for the whole point record and the full source_product_card per hit.","layer":"L1","input_schema":{"properties":{"query":{"default":"","title":"Query","type":"string"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Filters"},"world":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"World"},"max_points":{"default":3,"title":"Max Points","type":"integer"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit"},"offset":{"default":0,"title":"Offset","type":"integer"},"verbosity":{"default":"compact","enum":["compact","full"],"title":"Verbosity","type":"string"}},"title":"FindDataSourcesInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"properties":{"query":{"default":"","title":"Query","type":"string"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Filters"},"world":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"World"},"max_points":{"default":3,"title":"Max Points","type":"integer"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit"},"offset":{"default":0,"title":"Offset","type":"integer"},"verbosity":{"default":"compact","enum":["compact","full"],"title":"Verbosity","type":"string"}},"title":"FindDataSourcesInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"CatalogResponse","type":"object"},"title":"Find Data Sources","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"find_views","version":"1.0.0","description":"Look up the vetted analytic VIEWS for a question before you query. A view is the decision that comes before any table or chart: who is counted (population), against what base, compared to what, over which period and vintage, and what one row is (grain); plus the weight, the named measures, the forms that draw it (draw_as), how to reach the data (reach: the typed tool that carries the population and base first, then the source codes to read with describe_data_source and query_substrate), the rules that must hold and the ways the view goes wrong or contradicts another view (contradicts_if). Pass the user's question in their words; add a domain (ma_market, ma_benefits, hospital_prices, payer_rates, medicare_benchmark, ma_stars, medicaid, marketplace, drug_pricing, formulary, pbm, providers, employer, mlr, hospital_quality, drug_policy, ma_value, cross_domain) or a level (executive for a headline, actuarial for weights, cohorts, decompositions and distributions, detailed for row-level lookups) when you know it. Returns up to 8 views, best first; the default is 4. Use the returned population, base and period in your call and say them in the answer. A view is analytical guidance: it grants no data access and proves no coverage for the places, dates or populations in your question. Verify coverage with the source's own card before you quote a number. A question no view covers is composed from the same fields.","layer":"L1","input_schema":{"properties":{"question":{"default":"","title":"Question","type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Domain"},"level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Level"},"limit":{"default":4,"title":"Limit","type":"integer"}},"title":"FindViewsInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["A view is guidance, not data: it grants no access to the tools or sources it names and proves no coverage for the places, dates or populations in the question.","Ranking is deterministic word overlap with the domain's vocabulary; a question phrased far from the catalog's words may rank a neighbouring view first. Pass a domain or a level to narrow it."],"parameter_schema":{"properties":{"question":{"default":"","title":"Question","type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Domain"},"level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Level"},"limit":{"default":4,"title":"Limit","type":"integer"}},"title":"FindViewsInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"FindViewsResponse","type":"object"},"title":"Find Views","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_exchange_plan_profile","version":"1.0.0","description":"One ACA Marketplace (healthcare.gov / HIX) plan's profile for a plan year, every field tagged with the CCIIO PUF it came from. Give plan_id (the 14-character HIOS standard component id, e.g. 38344AK1060001) for the plan: issuer, metal level, plan type (HMO/PPO/EPO/POS), Individual vs SHOP, on/off exchange, network, county footprint, premium benchmarks at age 21/40/60 (min across the plan's rating areas, plus the age-40 max), the per-age premium curve from the Rate PUF (include_rate_curve, default true), headline cost shares (PCP / specialist / ER / urgent care / generic drug copay, inpatient coinsurance), CMS quality stars, and the issuer's individual-market MLR. Or give state (+ optional plan_year, metal_level, issuer_id, plan_type, on_off_exchange) for the bounded list of that state's plans, cheapest age-40 premium first. plan_year defaults to the latest year held (PY2014-2026). Deductible / MOOP are returned as not_available (not in the composed profile). FFM states only: a state-based marketplace (CA, NY, PA, GA, ...) is absent at source and the tool says so rather than returning nothing silently.","layer":"L2","input_schema":{"properties":{"plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Plan Id"},"plan_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Plan Year"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"metal_level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Metal Level"},"issuer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issuer Id"},"plan_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Plan Type"},"on_off_exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"On Off Exchange"},"include_rate_curve":{"default":true,"title":"Include Rate Curve","type":"boolean"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit"}},"title":"ExchangePlanProfileInput","type":"object"},"invariants":["plan_id_normalized_to_14_char_base","is_current_only_on_rate_puf","bounded_rows","not_found_distinguished","not_available_explicit"],"underlying_silver_tables_for_pinning":["medicare_silver.fact_exchange_plan_profile_v2","medicare_semantic.vw_rate_puf_current"],"semantic_views_used":[],"known_gaps":["FFM (healthcare.gov) states only; state-based marketplaces are absent at source.","Deductible / MOOP are not in the composed profile (untyped raw JSON in the Plan Attributes PUF today) and are returned as not_available.","premium_age21/40/60 are the MIN across the plan's rating areas (age-40 MAX also given); county-grain premium needs the rating area (use rate_curve / the Rate PUF).","Cost shares are the base variant (-01) as filed; CSR variants differ. Quality only for CMS-rated plans in PY2023/2024/2026; MLR only PY2019-2024; PY2015 premiums thin at source; medical plans only (v1)."],"parameter_schema":{"properties":{"plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Plan Id"},"plan_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Plan Year"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"metal_level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Metal Level"},"issuer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issuer Id"},"plan_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Plan Type"},"on_off_exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"On Off Exchange"},"include_rate_curve":{"default":true,"title":"Include Rate Curve","type":"boolean"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit"}},"title":"ExchangePlanProfileInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"ExchangePlanProfileResponse","type":"object"},"title":"Get Exchange Plan Profile","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_medicaid_rate","version":"0.2.0","description":"State Medicaid fee-for-service (FFS) rates by code from every state's published fee schedules, with history, cross-state comparison and the Medicare benchmark. Five modes: lookup (state + code(s): the rate in force today or on as_of, with its unit, type, schedule, effective date and source), compare (one code across every state that publishes it, on one basis, with the national median, quartiles, ratio and rank), trend (one state x code: the dated rates by key with the change at each step), changes (every rate that moved in a state in a date window: increase, decrease, new_code, pct_change), vs_medicare (a state's Medicaid rates as a share of the Medicare PFS non-facility rate for the same codes).\n\nUse cases: 'What does Arizona Medicaid pay for 97153 (ABA)?'; 'Which states pay the most for T1019 personal care per hour?'; 'How has Ohio's H2019 rate moved since 2021?'; 'What changed in Florida's behavioral health rates this year?'; 'How does Texas Medicaid compare with Medicare for 99213?'.\n\nA rate is dated by its own effective date (schedules reprint old rates in each edition; the latest edition printing a dated rate wins; in force = the latest dated rate on or before the day, for a key the current edition still prints). Every rate names its unit (rate_unit, unit_minutes) and type (fee, per_diem, percent_of_charges, conversion_factor, manual_pricing, not_covered); a key with more than one rate for the same date is served flagged ambiguous_key and never averaged; compare keeps one basis (per_hour for time units) and lists other-basis states as not compared. These are the state's FFS maximums, never managed-care negotiated rates. Coverage is state by state (47 states on 2026-11-02): a state with no rows is not built yet, not zero.\n\nSOURCE: vlada_curated.vw_state_medicaid_rate_v2 (one row per published rate with its source file sha256 and locator) and the States lane's views vw_state_medicaid_rate_change_v1, _compare_v1, _vs_medicare_v1 (M2).","layer":"L2","input_schema":{"properties":{"mode":{"default":"lookup","description":"lookup (state + code(s)), compare (code across states), trend (state + code by dated rate), changes (state, date window), vs_medicare (state [+ code]: Medicaid as a share of Medicare PFS).","enum":["lookup","compare","trend","changes","vs_medicare"],"title":"Mode","type":"string"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state code (AZ). Required for lookup, trend, changes, vs_medicare.","title":"State"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"One procedure / service code (97153, H2019, T1019). Required for compare and trend.","title":"Code"},"codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Up to 25 codes for lookup, in place of code.","title":"Codes"},"code_system":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"cpt | hcpcs | local | drg | apc ... as the schedule labels it; optional (compare maps 5-character CPT/HCPCS to HCPCS).","title":"Code System"},"service_line":{"anyOf":[{"enum":["aba_ei","behavioral_health","sud","hcbs","idd","professional","lab","dme","anesthesia","dental","vision","home_health","hospice","transport","outpatient_hospital","inpatient_hospital","nursing_facility","fqhc_rhc","pharmacy","other"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter: aba_ei, behavioral_health, sud, hcbs, idd, professional, ...","title":"Service Line"},"program":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter: the program / waiver as the schedule names it (contains match).","title":"Program"},"provider_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter: the provider type as the schedule names it (contains match).","title":"Provider Type"},"modifiers":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Modifier string as printed (HO, 'HM U1'); '' for no modifier. compare defaults to no modifier.","title":"Modifiers"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD: the rate in force on that day (lookup). Default: today.","title":"As Of"},"date_from":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD (changes, on the rate's effective date). Default: 24 months before date_to.","title":"Date From"},"date_to":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD (changes). Default: today.","title":"Date To"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500).","title":"Limit"}},"title":"MedicaidRateInput","type":"object"},"invariants":["rate_dated_by_effective_date","rate_unit_always_named","ambiguous_keys_never_blended","one_basis_per_comparison","in_force_or_as_of","bounded_rows","not_found_distinguished"],"underlying_silver_tables_for_pinning":["vlada_curated.vw_state_medicaid_rate_v2","vlada_curated.vw_state_medicaid_rate_change_v1","vlada_curated.vw_state_medicaid_rate_compare_v1","vlada_curated.vw_state_medicaid_rate_vs_medicare_v1"],"semantic_views_used":["vlada_curated.vw_state_medicaid_rate_change_v1","vlada_curated.vw_state_medicaid_rate_compare_v1","vlada_curated.vw_state_medicaid_rate_vs_medicare_v1"],"known_gaps":["Coverage is state by state (47 states on 2026-11-02; 147 of 255 state x service-line cells served): a state or line with no rows is not built yet, not zero.","A printing that holds more than one rate for the same date is served flagged ambiguous_key with its low and high, and kept out of compare (1 key on 2026-11-02 after the dated rule; 11,518 when keyed by edition).","History depth varies by state (back to 2021 in 71 of 147 cells; some schedules one dated rate).","vs_medicare joins only no-modifier, single-rate keys with a per-service / unit / visit / 15_min unit and a 5-character CPT/HCPCS code; the Medicare side is PFS non-facility, latest year, unweighted mean of the state's localities, so a per-15-minute Medicaid rate against a per-service Medicare amount is not like for like.","compare and trend read one code at a time; lookup and vs_medicare take up to 25 codes."],"parameter_schema":{"properties":{"mode":{"default":"lookup","description":"lookup (state + code(s)), compare (code across states), trend (state + code by dated rate), changes (state, date window), vs_medicare (state [+ code]: Medicaid as a share of Medicare PFS).","enum":["lookup","compare","trend","changes","vs_medicare"],"title":"Mode","type":"string"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state code (AZ). Required for lookup, trend, changes, vs_medicare.","title":"State"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"One procedure / service code (97153, H2019, T1019). Required for compare and trend.","title":"Code"},"codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Up to 25 codes for lookup, in place of code.","title":"Codes"},"code_system":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"cpt | hcpcs | local | drg | apc ... as the schedule labels it; optional (compare maps 5-character CPT/HCPCS to HCPCS).","title":"Code System"},"service_line":{"anyOf":[{"enum":["aba_ei","behavioral_health","sud","hcbs","idd","professional","lab","dme","anesthesia","dental","vision","home_health","hospice","transport","outpatient_hospital","inpatient_hospital","nursing_facility","fqhc_rhc","pharmacy","other"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter: aba_ei, behavioral_health, sud, hcbs, idd, professional, ...","title":"Service Line"},"program":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter: the program / waiver as the schedule names it (contains match).","title":"Program"},"provider_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter: the provider type as the schedule names it (contains match).","title":"Provider Type"},"modifiers":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Modifier string as printed (HO, 'HM U1'); '' for no modifier. compare defaults to no modifier.","title":"Modifiers"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD: the rate in force on that day (lookup). Default: today.","title":"As Of"},"date_from":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD (changes, on the rate's effective date). Default: 24 months before date_to.","title":"Date From"},"date_to":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD (changes). Default: today.","title":"Date To"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500).","title":"Limit"}},"title":"MedicaidRateInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"MedicaidRateResponse","type":"object"},"title":"Get Medicaid Rate","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_network_breadth","version":"0.2.0","description":"How broad a Medicare Advantage plan's published provider network is, county by county, against the other plans sold there: for a contract or CMS plan id and plan year (2026 or 2027), each county in its service area with the providers it lists there, the county's listed universe (every MA plan's published directory in that county), breadth (the share), its rank among the county's individual plans, and the rivals' median and best. Narrow to one specialty in CMS's network-adequacy vocabulary (Primary Care, Cardiology, Psychiatry, ...), a state, or one county; with a county, the rival plans are returned ranked.\n\nUse cases: 'Is H5938's network narrower than its rivals in Leon County?'; 'Where does this PPO rank on cardiologists in Florida?'; 'Which plan in Cook County lists the most psychiatrists for 2027?'.\n\nBreadth is a share of what MA plans list, not of every practising clinician. Every row carries the share of the plan's providers found by name match and the share carried from the other year's list, so a printed-PDF plan is not silently compared with an API plan. Specialty comes from NPPES's taxonomy, not the directory's label. The publish is pinned by dataset_id.\n\nSOURCE: medicare_silver.ma_network_plan_county_v1, built from the Data Tracker's directory table (medicare_bronze.ma_directory_plan_npi_site_v1), NPPES, and the CMS plan service area.","layer":"L2","input_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5938). One of contract_id / cms_plan_id.","title":"Contract Id"},"cms_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS plan id H1234-001 or H1234-001-000.","title":"Cms Plan Id"},"plan_year":{"description":"2026 or 2027 (the directory year).","enum":[2026,2027],"title":"Plan Year","type":"integer"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500); summaries are always whole.","title":"Limit"},"county_fips":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"5-digit county FIPS (12073); with it, the rival plans in that county are returned.","title":"County Fips"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state; narrows to the plan's counties in that state.","title":"State"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Normalized specialty (CMS MA network-adequacy type, e.g. 'Cardiology', 'Primary Care'); omit for every provider.","title":"Specialty"}},"required":["plan_year"],"title":"NetworkBreadthInput","type":"object"},"invariants":["dataset_id_pinned","distinct_npis_not_rows","source_mix_on_every_row","uncovered_is_not_empty","bounded_rows"],"underlying_silver_tables_for_pinning":["medicare_silver.ma_network_plan_county_v1","medicare_silver.fact_ma_landscape"],"semantic_views_used":[],"known_gaps":["Coverage follows the directory build (stage 25: 99.17% of 2026 MA members, 96.42% of 2027 members from 2027 sources); an uncovered contract answers no_coverage, and a plan with listings only outside its CMS service area has no breadth rows.","Name-matched lists under-count: names that resolve to no single NPI are dropped, so a printed-PDF plan can read narrower than it is (matched_share says how much of the list is name-matched).","About 2.5% of listings have a ZIP with no county and sit outside every county count.","Contract-level directories (one network for every plan in the contract) are applied to each plan sold in the county (contract_level_share)."],"parameter_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5938). One of contract_id / cms_plan_id.","title":"Contract Id"},"cms_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS plan id H1234-001 or H1234-001-000.","title":"Cms Plan Id"},"plan_year":{"description":"2026 or 2027 (the directory year).","enum":[2026,2027],"title":"Plan Year","type":"integer"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500); summaries are always whole.","title":"Limit"},"county_fips":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"5-digit county FIPS (12073); with it, the rival plans in that county are returned.","title":"County Fips"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state; narrows to the plan's counties in that state.","title":"State"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Normalized specialty (CMS MA network-adequacy type, e.g. 'Cardiology', 'Primary Care'); omit for every provider.","title":"Specialty"}},"required":["plan_year"],"title":"NetworkBreadthInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"NetworkBreadthResponse","type":"object"},"title":"Get Network Breadth","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_network_change","version":"0.2.0","description":"Who joined and who left a Medicare Advantage plan's published network between two directory years (2026 to 2027): the NPIs that stayed, joined and left, with rates, on published units only. The method: members are NPIs the payer printed, served by API or exported to Plan Finder, or name-matched at grade A/B; 2027 rows carried back from a 2026 directory are excluded; only ZIP3 areas the unit lists in both years count, so a service-area change does not read as an exit. By contract or by the publisher's own plan id.\n\nUse cases: 'Did H5938 lose providers for 2027?'; 'How much of Wellcare H1416's Texas network turned over?'.\n\nA directory signal is never evidence of a contract ending on its own (the method's public-confirmation rule); the health-system rollup and the exit signal are not served here. Both years must be covered or the answer is NO_COVERAGE.\n\nSOURCE: medicare_bronze.ma_directory_plan_npi_site_v1 (the Data Tracker's directory build).","layer":"L2","input_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5938). One of contract_id / cms_plan_id.","title":"Contract Id"},"cms_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS plan id (H1234-001-000): the publisher's own unit when it attached one.","title":"Cms Plan Id"},"from_year":{"default":2026,"description":"The earlier directory year.","enum":[2026,2027],"title":"From Year","type":"integer"},"to_year":{"default":2027,"description":"The later directory year.","enum":[2026,2027],"title":"To Year","type":"integer"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the listed location; optional.","title":"State"}},"title":"NetworkChangeInput","type":"object"},"invariants":["dataset_id_pinned","published_units_only","carry_back_excluded","zip3_in_both_years","uncovered_is_not_empty"],"underlying_silver_tables_for_pinning":["medicare_bronze.ma_directory_plan_npi_site_v1"],"semantic_views_used":[],"known_gaps":["No health-system rollup and no exit signal here (the method's steps 4-5 need the facility affiliation and dim_facility_system tables and a public confirmation); counts are by contract or plan.","Humana's 2027 joined rate reads high in the method's own scale table and may be a printing or matching artifact; treat a large joined count as unverified.","A contract uncovered in either year answers NO_COVERAGE."],"parameter_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5938). One of contract_id / cms_plan_id.","title":"Contract Id"},"cms_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS plan id (H1234-001-000): the publisher's own unit when it attached one.","title":"Cms Plan Id"},"from_year":{"default":2026,"description":"The earlier directory year.","enum":[2026,2027],"title":"From Year","type":"integer"},"to_year":{"default":2027,"description":"The later directory year.","enum":[2026,2027],"title":"To Year","type":"integer"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the listed location; optional.","title":"State"}},"title":"NetworkChangeInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"NetworkChangeResponse","type":"object"},"title":"Get Network Change","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_network_groups","version":"0.2.0","description":"Which physician groups and health systems a Medicare Advantage contract's published network covers, and how much of each: for a contract and plan year (2026 or 2027), every billing group its listed clinicians bill Medicare through (or every health system of the hospitals they are affiliated with), with the clinicians the contract lists, the group's own clinician count and the share; or search one group or system by name across every contract.\n\nUse cases: 'What share of Virginia Mason's doctors does Regence list?'; 'Which MA contracts list most of Optum's physicians in Texas?'; 'Which large groups does H5938 cover?'.\n\nGroups are CMS's Medicare reassignment (the group a clinician bills through); systems are CMS's hospital affiliation through the hospital system map. A clinician in several groups counts in each. A share is of the group's Medicare-enrolled clinicians, as listed in the plan's published directory. The publish is pinned by dataset_id.\n\nSOURCE: medicare_silver.ma_network_contract_group_v1 (the Data Tracker's directory table x CMS PECOS reassignment x CMS Doctors and Clinicians facility affiliation x the hospital system map).","layer":"L2","input_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H3817). One of contract_id / name.","title":"Contract Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Billing group or health system name (contains match, e.g. 'Virginia Mason'); searches every contract.","title":"Name"},"plan_year":{"default":2027,"description":"2026 or 2027 (default 2027).","enum":[2026,2027],"title":"Plan Year","type":"integer"},"level":{"default":"group","description":"'group' (default; the billing group clinicians reassign to in Medicare) or 'system' (the health system of their hospitals).","enum":["group","system"],"title":"Level","type":"string"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the group; optional (groups only).","title":"State"},"min_clinicians":{"default":10,"description":"Smallest group or system returned, by its own clinician count (default 10).","title":"Min Clinicians","type":"integer"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500).","title":"Limit"}},"title":"NetworkGroupsInput","type":"object"},"invariants":["dataset_id_pinned","distinct_npis_not_rows","uncovered_is_not_empty","bounded_rows"],"underlying_silver_tables_for_pinning":["medicare_silver.ma_network_contract_group_v1","medicare_silver.fact_ma_landscape"],"semantic_views_used":[],"known_gaps":["Groups come from Medicare reassignment: a group's clinicians who do not bill Medicare are not counted.","Contract level: a contract with several networks (HMO and PPO plans) is read as one.","Coverage follows the directory build (stage 25); an uncovered contract answers no_coverage."],"parameter_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H3817). One of contract_id / name.","title":"Contract Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Billing group or health system name (contains match, e.g. 'Virginia Mason'); searches every contract.","title":"Name"},"plan_year":{"default":2027,"description":"2026 or 2027 (default 2027).","enum":[2026,2027],"title":"Plan Year","type":"integer"},"level":{"default":"group","description":"'group' (default; the billing group clinicians reassign to in Medicare) or 'system' (the health system of their hospitals).","enum":["group","system"],"title":"Level","type":"string"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the group; optional (groups only).","title":"State"},"min_clinicians":{"default":10,"description":"Smallest group or system returned, by its own clinician count (default 10).","title":"Min Clinicians","type":"integer"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500).","title":"Limit"}},"title":"NetworkGroupsInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"NetworkGroupsResponse","type":"object"},"title":"Get Network Groups","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_network_system_change","version":"0.2.0","description":"Which health systems (or specialties) Medicare Advantage networks gained and lost between 2026 and 2027, from the plans' own published directories: for a contract, every health system with the clinicians listed in each year, how many stayed, left and joined, and an exit or join signal where a system's listing collapsed while the rest of the network held; or search one health system by name across every contract.\n\nUse cases: 'Did Humana drop Ohio State for 2027?'; 'Which systems left H5216's network?'; 'Which contracts lost cardiologists for 2027?'.\n\nLike for like: only each contract's own-year lists (no stand-ins), only ZIP3 areas it lists in both years, members only. A signal is a DIRECTORY SIGNAL to verify with the system or plan, never proof a contract ended; a contract whose source changed between years carries no signal. The publish is pinned by dataset_id.\n\nSOURCE: medicare_silver.ma_network_change_v1 (the Data Tracker's directory table x CMS Doctors and Clinicians facility affiliation x the hospital system map).","layer":"L2","input_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5216). One of contract_id / system.","title":"Contract Id"},"system":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Health system name (contains match, e.g. 'Ohio State'); searches every contract.","title":"System"},"rollup":{"default":"system","description":"'system' (default; health systems) or 'specialty' (CMS network-adequacy types).","enum":["system","specialty"],"title":"Rollup","type":"string"},"signals_only":{"default":false,"description":"Return only system rows flagged as an exit or join signal.","title":"Signals Only","type":"boolean"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500).","title":"Limit"}},"title":"NetworkSystemChangeInput","type":"object"},"invariants":["dataset_id_pinned","like_for_like_units","signal_is_not_proof","bounded_rows"],"underlying_silver_tables_for_pinning":["medicare_silver.ma_network_change_v1","medicare_silver.fact_ma_landscape"],"semantic_views_used":[],"known_gaps":["Only contracts with an own-year list in both 2026 and 2027 are compared; the 40 contracts whose 2027 list is their 2026 directory standing in have no change rows.","A clinician affiliated with several systems counts in each; system membership is CMS's hospital affiliation (2026-05-29) through the hospital system map.","A publisher that moved from a thin API snapshot to a full one reads as a high joined rate; joined rates above 20% are flagged unverified."],"parameter_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5216). One of contract_id / system.","title":"Contract Id"},"system":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Health system name (contains match, e.g. 'Ohio State'); searches every contract.","title":"System"},"rollup":{"default":"system","description":"'system' (default; health systems) or 'specialty' (CMS network-adequacy types).","enum":["system","specialty"],"title":"Rollup","type":"string"},"signals_only":{"default":false,"description":"Return only system rows flagged as an exit or join signal.","title":"Signals Only","type":"boolean"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500).","title":"Limit"}},"title":"NetworkSystemChangeInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"NetworkSystemChangeResponse","type":"object"},"title":"Get Network System Change","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_plan_hospitals","version":"0.2.0","description":"The hospitals in a Medicare Advantage plan's published provider network for 2026 or 2027, by contract or CMS plan id: each hospital (CMS certification number, name, state, health system) with the evidence that it is in network: the hospital's own NPI listed in the directory, or how many of the clinicians CMS records as affiliated with it the plan lists (and the share). Narrow by hospital state or health system; choose the weakest evidence to return.\n\nUse cases: 'Which hospitals are in H5938's 2027 network?'; 'Is the Cleveland Clinic in this plan?'; 'Which HCA hospitals does H1036 list in Florida?'.\n\nA hospital's own NPI in the directory is strong evidence; many affiliated clinicians listed is good evidence; a few affiliated clinicians is weak and labelled so. A hospital absent from the list is 'no evidence in the published directory', never 'out of network'. The publish is pinned by dataset_id.\n\nSOURCE: medicare_silver.ma_network_plan_hospital_v1 (the Data Tracker's directory table x CMS hospital enrollment NPI = CCN x CMS Doctors and Clinicians facility affiliation x the hospital system map).","layer":"L2","input_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5938). One of contract_id / cms_plan_id.","title":"Contract Id"},"cms_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS plan id H1234-001 or H1234-001-000.","title":"Cms Plan Id"},"plan_year":{"description":"2026 or 2027 (the directory year).","enum":[2026,2027],"title":"Plan Year","type":"integer"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500); summaries are always whole.","title":"Limit"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the hospital; optional.","title":"State"},"system":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Health system name (contains match, e.g. 'HCA'); optional.","title":"System"},"min_evidence":{"default":"good","description":"Weakest evidence returned: 'strong' (the hospital's own NPI is in the directory), 'good' (default: strong, or 10+ of its affiliated clinicians and 20%+ of them listed), or 'any' (also hospitals with a few affiliated clinicians listed).","enum":["strong","good","any"],"title":"Min Evidence","type":"string"}},"required":["plan_year"],"title":"PlanHospitalsInput","type":"object"},"invariants":["dataset_id_pinned","evidence_grade_on_every_row","absence_is_not_out_of_network","bounded_rows"],"underlying_silver_tables_for_pinning":["medicare_silver.ma_network_plan_hospital_v1"],"semantic_views_used":[],"known_gaps":["Many directories list clinicians and not facilities: a hospital reached only through affiliated clinicians is inferred from CMS's affiliation file (2026-05-29), not printed by the plan.","Affiliation covers hospitals where CMS records clinicians (4,606); a hospital with no affiliated clinicians can appear only by its own NPI.","Coverage follows the directory build (stage 25); an uncovered contract answers no_coverage."],"parameter_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5938). One of contract_id / cms_plan_id.","title":"Contract Id"},"cms_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS plan id H1234-001 or H1234-001-000.","title":"Cms Plan Id"},"plan_year":{"description":"2026 or 2027 (the directory year).","enum":[2026,2027],"title":"Plan Year","type":"integer"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Rows to return (default 50, max 500); summaries are always whole.","title":"Limit"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the hospital; optional.","title":"State"},"system":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Health system name (contains match, e.g. 'HCA'); optional.","title":"System"},"min_evidence":{"default":"good","description":"Weakest evidence returned: 'strong' (the hospital's own NPI is in the directory), 'good' (default: strong, or 10+ of its affiliated clinicians and 20%+ of them listed), or 'any' (also hospitals with a few affiliated clinicians listed).","enum":["strong","good","any"],"title":"Min Evidence","type":"string"}},"required":["plan_year"],"title":"PlanHospitalsInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"PlanHospitalsResponse","type":"object"},"title":"Get Plan Hospitals","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_plan_network","version":"0.2.0","description":"The provider network a Medicare Advantage plan publishes: the NPIs its directory lists for a plan year (2026 or 2027), by contract or CMS plan id, with the source of every listing (the payer's own Plan-Net API, the printed directory, a name match to NPPES with its grade, or the Medicare Plan Finder export), the counts by source and grade, and a page of listings with name, specialty, location and the file and page each came from. Filter by state, ZIP or specialty.\n\nUse cases: 'How many providers does H5959 list for 2027?'; 'Which cardiologists are in H5938's network in Tallahassee?'; 'Is this plan's directory API-served or printed?'.\n\nMembership is DISTINCT NPIs, never row counts. Name-matched rows are flagged by grade and never presented as printed; listings whose name resolves to no single NPI are kept without an NPI and are not members. A contract with no rows is UNCOVERED (the open-gap list), never 'no network'. 2027 rows carried back from a 2026 directory are labelled (plan_key_basis). The publish is pinned by dataset_id.\n\nSOURCE: medicare_bronze.ma_directory_plan_npi_site_v1 (the Data Tracker's directory build; every row names its url, page and raw_sha256).","layer":"L2","input_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5938). One of contract_id / cms_plan_id.","title":"Contract Id"},"cms_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS plan id H1234-001 or H1234-001-000 (contract-plan[-segment]).","title":"Cms Plan Id"},"plan_year":{"description":"2026 or 2027 (the directory year).","enum":[2026,2027],"title":"Plan Year","type":"integer"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the listed location; optional.","title":"State"},"zip5":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"5-digit ZIP of the listed location; optional.","title":"Zip5"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Specialty as printed (contains match); optional.","title":"Specialty"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Listings to return (default 50, max 500); counts are always whole.","title":"Limit"}},"required":["plan_year"],"title":"PlanNetworkInput","type":"object"},"invariants":["dataset_id_pinned","distinct_npis_not_rows","matched_never_presented_as_printed","uncovered_is_not_empty","bounded_rows"],"underlying_silver_tables_for_pinning":["medicare_bronze.ma_directory_plan_npi_site_v1","medicare_silver.fact_ma_landscape","medicare_silver.ma_network_active_v1"],"semantic_views_used":[],"known_gaps":["Coverage: 99.1% of 2026 MA members and 96.1% of 2027 members from 2027 sources (stage 21, 2026-11-02); the open-gap contracts (HCSC, Geisinger 2027, Highmark Wholecare, Elderplan, Mercy Care, Elevate, CarePartners CT, six thin Elevance contracts) are UNCOVERED and answer NO_COVERAGE.","Listings whose printed name does not resolve to a single NPI (about 11.3M rows, grade C or D, mostly Humana PDFs) are kept without an NPI and are not counted as members.","Matched grade N rows can lack city, state and ZIP; page is a string.","42 contracts' (1,132,045 members') 2027 rows are their 2026 directory applied through the CMS crosswalk (plan_key_basis *_2026_plan_via_crosswalk): labelled, not a 2027 directory."],"parameter_schema":{"properties":{"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS contract id (H5938). One of contract_id / cms_plan_id.","title":"Contract Id"},"cms_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CMS plan id H1234-001 or H1234-001-000 (contract-plan[-segment]).","title":"Cms Plan Id"},"plan_year":{"description":"2026 or 2027 (the directory year).","enum":[2026,2027],"title":"Plan Year","type":"integer"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the listed location; optional.","title":"State"},"zip5":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"5-digit ZIP of the listed location; optional.","title":"Zip5"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Specialty as printed (contains match); optional.","title":"Specialty"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Listings to return (default 50, max 500); counts are always whole.","title":"Limit"}},"required":["plan_year"],"title":"PlanNetworkInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"PlanNetworkResponse","type":"object"},"title":"Get Plan Network","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"how_to_join","version":"1.3.0","description":"Return the fail-closed measured way to join two Vlada substrate tables, including an explicit DIRECT_OK, DIRECT_DECLARED_KEY, NEEDS_GRAIN, ROUTE_THROUGH_DIM, ROUTE_MULTIHOP, or DO_NOT_SERVE directive. Direct joins come from (in order) the measured connection registry, the VALIDATED join graph (catalog.json join_edges: uniqueness >= 0.999 and match >= 0.80, measured live), or the semantic layer's declared shared surrogate key (DIRECT_DECLARED_KEY, labelled not-live-measured); a validated or declared direct join is always preferred over a route and never refused. Route coverage (min_coverage) is the weaker side of the weakest hop; a route under 50% is labelled low_coverage_route. Unproved composite, NEEDS_GRAIN, quarantined, impossible, or N:M direct evidence cannot be served. With only table_a, it lists every executable connection from that table.","layer":"L2","input_schema":{"properties":{"table_a":{"title":"Table A","type":"string"},"table_b":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Table B"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit"},"offset":{"default":0,"title":"Offset","type":"integer"}},"required":["table_a"],"title":"HowToJoinInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["Only joins resolvable to physical columns + measurable live are in the registry; big-fact joins are dimension-routed. Absence of a verified join means 'not proven', not 'impossible'."],"parameter_schema":{"properties":{"table_a":{"title":"Table A","type":"string"},"table_b":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Table B"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit"},"offset":{"default":0,"title":"Offset","type":"integer"}},"required":["table_a"],"title":"HowToJoinInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"CatalogResponse","type":"object"},"title":"How To Join","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"is_provider_in_plan","version":"0.2.0","description":"Every Medicare Advantage plan whose published directory lists an NPI for a plan year (2026 or 2027): contract, CMS plan id, the source of the listing (the payer's API, the printed directory, a name match with its grade, or the Plan Finder export), the location as listed, and the file and page it came from. Narrow by state or contract.\n\nUse cases: 'Which MA plans list NPI 1275507170 for 2027?'; 'Is Dr X in Humana's Florida network?'.\n\nA listing is evidence the directory names the NPI; an absence is 'not listed in the published directory' for covered contracts only (an uncovered contract says nothing). Name-matched rows are flagged by grade. The publish is pinned by dataset_id.\n\nSOURCE: medicare_bronze.ma_directory_plan_npi_site_v1 (every row names its url, page and raw_sha256).","layer":"L2","input_schema":{"properties":{"npi":{"description":"10-digit NPI.","title":"Npi","type":"string"},"plan_year":{"description":"2026 or 2027.","enum":[2026,2027],"title":"Plan Year","type":"integer"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the listed location; optional.","title":"State"},"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Narrow to one contract (H5938); optional.","title":"Contract Id"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Plans to return (default 50, max 500).","title":"Limit"}},"required":["npi","plan_year"],"title":"ProviderInPlanInput","type":"object"},"invariants":["dataset_id_pinned","matched_never_presented_as_printed","absence_scoped_to_covered_contracts","bounded_rows"],"underlying_silver_tables_for_pinning":["medicare_bronze.ma_directory_plan_npi_site_v1"],"semantic_views_used":[],"known_gaps":["An NPI absent from every directory is 'not listed' only for the covered contracts (99.1% of 2026 members, 96.1% of 2027 from 2027 sources, stage 21); the open-gap contracts say nothing.","A plan listed through a 2026 directory carried back to 2027 (plan_key_basis *_2026_plan_via_crosswalk) is labelled."],"parameter_schema":{"properties":{"npi":{"description":"10-digit NPI.","title":"Npi","type":"string"},"plan_year":{"description":"2026 or 2027.","enum":[2026,2027],"title":"Plan Year","type":"integer"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"2-letter state of the listed location; optional.","title":"State"},"contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Narrow to one contract (H5938); optional.","title":"Contract Id"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Plans to return (default 50, max 500).","title":"Limit"}},"required":["npi","plan_year"],"title":"ProviderInPlanInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"ProviderInPlanResponse","type":"object"},"title":"Is Provider In Plan","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"plan_hospital_price","version":"1.5.0","description":"One hospital, one code, the rate by payer and plan name as the hospital filed it (where negotiated rates by insurer live today; the insurer-file / TiC tools are coming soon). Dry-run a bounded hospital fact_hospital_chargemaster proof. Requires hospital_ccn and billing_code, plans Iceberg files/bytes before materializing rows, and returns a receipt-shaped plan.","layer":"L2","input_schema":{"description":"Bounded hospital fact proof request.","properties":{"hospital_ccn":{"title":"Hospital Ccn","type":"string"},"billing_code":{"title":"Billing Code","type":"string"},"version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Id"},"payer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Payer Name"},"plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Plan Name"},"billing_class":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Billing Class"},"current_only":{"default":true,"title":"Current Only","type":"boolean"},"require_byte_provenance":{"default":true,"title":"Require Byte Provenance","type":"boolean"},"max_rows":{"default":10000,"maximum":100000,"minimum":1,"title":"Max Rows","type":"integer"},"max_planned_files":{"default":500,"maximum":10000,"minimum":1,"title":"Max Planned Files","type":"integer"},"max_planned_bytes":{"default":268435456,"maximum":10737418240,"minimum":1,"title":"Max Planned Bytes","type":"integer"}},"required":["hospital_ccn","billing_code"],"title":"HospitalPriceProofInput","type":"object"},"invariants":["bounded_fact_hospital_price_scope_v0"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster"],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"description":"Bounded hospital fact proof request.","properties":{"hospital_ccn":{"title":"Hospital Ccn","type":"string"},"billing_code":{"title":"Billing Code","type":"string"},"version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Id"},"payer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Payer Name"},"plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Plan Name"},"billing_class":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Billing Class"},"current_only":{"default":true,"title":"Current Only","type":"boolean"},"require_byte_provenance":{"default":true,"title":"Require Byte Provenance","type":"boolean"},"max_rows":{"default":10000,"maximum":100000,"minimum":1,"title":"Max Rows","type":"integer"},"max_planned_files":{"default":500,"maximum":10000,"minimum":1,"title":"Max Planned Files","type":"integer"},"max_planned_bytes":{"default":268435456,"maximum":10737418240,"minimum":1,"title":"Max Planned Bytes","type":"integer"}},"required":["hospital_ccn","billing_code"],"title":"HospitalPriceProofInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"ok","enum":["planned","ok","no_match","rejected_guardrail","too_large_for_sync","summary_from_cell_table"],"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"},"proof_id":{"default":"","title":"Proof Id","type":"string"},"receipt":{"additionalProperties":true,"title":"Receipt","type":"object"}},"title":"HospitalPriceProofResponse","type":"object"},"title":"Plan Hospital Price","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"poll_query","version":"1.0.0","description":"Poll the status of an async job submitted with submit_query. Returns queued/running/done/error and whether it is terminal. When done, read the result with fetch_query.","layer":"L2","input_schema":{"properties":{"job_id":{"title":"Job Id","type":"string"}},"required":["job_id"],"title":"JobIdInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"properties":{"job_id":{"title":"Job Id","type":"string"}},"required":["job_id"],"title":"JobIdInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"AsyncJobResponse","type":"object"},"title":"Poll Query","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"prove_hospital_price","version":"1.5.0","description":"One hospital, one code, the rate by payer and plan name with a receipt (where negotiated rates by insurer live today; the insurer-file / TiC tools are coming soon). Execute a bounded hospital chargemaster price proof and return rate summary values plus a receipt with source snapshot, filters, raw byte provenance, caveats, input hash, response hash, and replay pointer.","layer":"L2","input_schema":{"description":"Bounded hospital fact proof request.","properties":{"hospital_ccn":{"title":"Hospital Ccn","type":"string"},"billing_code":{"title":"Billing Code","type":"string"},"version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Id"},"payer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Payer Name"},"plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Plan Name"},"billing_class":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Billing Class"},"current_only":{"default":true,"title":"Current Only","type":"boolean"},"require_byte_provenance":{"default":true,"title":"Require Byte Provenance","type":"boolean"},"max_rows":{"default":10000,"maximum":100000,"minimum":1,"title":"Max Rows","type":"integer"},"max_planned_files":{"default":500,"maximum":10000,"minimum":1,"title":"Max Planned Files","type":"integer"},"max_planned_bytes":{"default":268435456,"maximum":10737418240,"minimum":1,"title":"Max Planned Bytes","type":"integer"}},"required":["hospital_ccn","billing_code"],"title":"HospitalPriceProofInput","type":"object"},"invariants":["bounded_fact_hospital_price_scope_v0"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster"],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"description":"Bounded hospital fact proof request.","properties":{"hospital_ccn":{"title":"Hospital Ccn","type":"string"},"billing_code":{"title":"Billing Code","type":"string"},"version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Id"},"payer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Payer Name"},"plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Plan Name"},"billing_class":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Billing Class"},"current_only":{"default":true,"title":"Current Only","type":"boolean"},"require_byte_provenance":{"default":true,"title":"Require Byte Provenance","type":"boolean"},"max_rows":{"default":10000,"maximum":100000,"minimum":1,"title":"Max Rows","type":"integer"},"max_planned_files":{"default":500,"maximum":10000,"minimum":1,"title":"Max Planned Files","type":"integer"},"max_planned_bytes":{"default":268435456,"maximum":10737418240,"minimum":1,"title":"Max Planned Bytes","type":"integer"}},"required":["hospital_ccn","billing_code"],"title":"HospitalPriceProofInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"ok","enum":["planned","ok","no_match","rejected_guardrail","too_large_for_sync","summary_from_cell_table"],"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"},"proof_id":{"default":"","title":"Proof Id","type":"string"},"receipt":{"additionalProperties":true,"title":"Receipt","type":"object"}},"title":"HospitalPriceProofResponse","type":"object"},"title":"Prove Hospital Price","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"prove_ma_enrollment_trend","version":"0.1.0","description":"Execute a bounded MA enrollment-trend proof. Returns the answer value plus a receipt with substrate, source snapshots, filters, guardrails, caveats, input hash, response hash, and replay pointer. Reads three silver tables (CPSC county, monthly-enrollment-plan, plan-crosswalks) at their published snapshots.","layer":"L2","input_schema":{"description":"Bounded MA enrollment-trend proof request.\n\nThe proof scope is intentionally narrow: a parent organization across a\nyear range, optionally filtered by state / plan_type / SNP type. The\nproof reads three silver tables (CPSC county-grain + monthly-enrollment-\nplan + plan-crosswalks) at their respective published snapshots.","properties":{"parent_org":{"title":"Parent Org","type":"string"},"year_range_start":{"maximum":2030,"minimum":2006,"title":"Year Range Start","type":"integer"},"year_range_end":{"maximum":2030,"minimum":2006,"title":"Year Range End","type":"integer"},"states":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"States"},"plan_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Plan Types"},"snp_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Snp Types"},"acknowledge_era_break":{"default":false,"description":"Retained for backward compat. The pre/post-2018 grain pivot was empirically falsified 2026-05-11; no era break is enforced. See docs/research/2026-05-11-cpsc-verification-ledger.md.","title":"Acknowledge Era Break","type":"boolean"},"max_contributing_rows":{"default":5000000,"maximum":50000000,"minimum":1,"title":"Max Contributing Rows","type":"integer"}},"required":["parent_org","year_range_start","year_range_end"],"title":"MAEnrollmentTrendProofInput","type":"object"},"invariants":["bounded_ma_enrollment_trend_scope_v0"],"underlying_silver_tables_for_pinning":["medicare_silver.enrollment_monthly_county","medicare_silver.enrollment_monthly_plan","medicare_silver.plan_crosswalks_annual","medicare_silver.monthly_contract_enrollment_summary"],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"description":"Bounded MA enrollment-trend proof request.\n\nThe proof scope is intentionally narrow: a parent organization across a\nyear range, optionally filtered by state / plan_type / SNP type. The\nproof reads three silver tables (CPSC county-grain + monthly-enrollment-\nplan + plan-crosswalks) at their respective published snapshots.","properties":{"parent_org":{"title":"Parent Org","type":"string"},"year_range_start":{"maximum":2030,"minimum":2006,"title":"Year Range Start","type":"integer"},"year_range_end":{"maximum":2030,"minimum":2006,"title":"Year Range End","type":"integer"},"states":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"States"},"plan_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Plan Types"},"snp_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Snp Types"},"acknowledge_era_break":{"default":false,"description":"Retained for backward compat. The pre/post-2018 grain pivot was empirically falsified 2026-05-11; no era break is enforced. See docs/research/2026-05-11-cpsc-verification-ledger.md.","title":"Acknowledge Era Break","type":"boolean"},"max_contributing_rows":{"default":5000000,"maximum":50000000,"minimum":1,"title":"Max Contributing Rows","type":"integer"}},"required":["parent_org","year_range_start","year_range_end"],"title":"MAEnrollmentTrendProofInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"ok","enum":["planned","ok","no_match","rejected_guardrail"],"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"},"proof_id":{"default":"","title":"Proof Id","type":"string"},"receipt":{"additionalProperties":true,"title":"Receipt","type":"object"}},"title":"MAEnrollmentTrendProofResponse","type":"object"},"title":"Prove MA Enrollment Trend","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"query","version":"0.3.0","description":"SAFE STUB. Given a catalog source FQN, return HOW to query it FROM THIS MCP -- and only paths executable here: query_substrate (sync, small) or submit_query -> poll_query -> fetch_query (async), each with the source's fqn and one working example SELECT carrying an explicit LIMIT (and WHERE is_current when the table is M-2 versioned). Never executes SQL. A source outside the queryable set (retired / partial / planned / unattributed) gets no executable path and the rule that excluded it. COLUMNS (0.3.0): example_sql names the first ~6 real columns instead of `SELECT *` when the source is in the committed columns snapshot (same one describe_data_source's `columns` field reads); falls back to `SELECT *` when it is not, never a guessed column list. IDENTIFIERS (2026-09-18): this accepts every identifier describe_data_source accepts -- the public source code, a catalog source id, or a table FQN -- and answers with the same what-to-type block, so the two can never disagree about whether an identifier exists.","layer":"L1","input_schema":{"properties":{"source_fqn":{"title":"Source Fqn","type":"string"},"sql_or_params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Sql Or Params"}},"required":["source_fqn"],"title":"QueryInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"properties":{"source_fqn":{"title":"Source Fqn","type":"string"},"sql_or_params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Sql Or Params"}},"required":["source_fqn"],"title":"QueryInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"CatalogResponse","type":"object"},"title":"Query","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"query_substrate","version":"1.1.0","description":"Set fresh=true for a user-requested saved-view update: execute without the result cache; all access and scan limits still apply. Run a read-only SQL SELECT directly over the Vlada cost-data substrate (Athena/Iceberg) and get the rows back, with provenance. Use this when the pre-built tools don't answer your exact question. WORKFLOW: first call find_data_sources / describe_data_source to find the table + read its card (grain, columns, and the CAVEATS you must apply — e.g. filter ghost rates, never blend across modifiers/methodologies), THEN write SQL against the table's fully-qualified name (e.g. vlada_curated.fact_hospital_chargemaster). RULES: read-only SELECT only (no INSERT/UPDATE/DDL — rejected); you may only query tables in the queryable set your account is entitled to (others are rejected); M-2 versioned tables must be filtered on is_current (injected for a single-table SELECT, otherwise rejected with the column named); results are LIMIT-bounded by your plan's per-call row cap (at most 10000), the delivered payload is bounded to ~47K chars, and the scan is cost-capped. Any bound that drops rows is reported as truncated:true with rows_returned + rows_dropped/total_rows_estimate and a caveat saying how to get the rest: aggregate in SQL (GROUP BY, COUNT, approx_percentile) or narrow the predicate, so the engine computes over the full set and returns the answer in a few rows. Vlada answers questions; it does not export whole tables: paging past the first page (OFFSET) and the bulk lane (submit_query) are not on free or Studio. Every result carries provenance (the engine, query id, bytes scanned, tables read). Apply the source card's methodology yourself: raw SQL does not enforce it.","layer":"L1","input_schema":{"properties":{"sql":{"title":"Sql","type":"string"},"max_rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Max Rows"},"fresh":{"default":false,"title":"Fresh","type":"boolean"}},"required":["sql"],"title":"QuerySubstrateInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["Raw SQL does NOT enforce a source's methodology (ghost-rate filter, modifier/methodology non-blending) — the agent must apply the caveats from the source card. For warranted, methodology-enforced numbers use the source's specialized tool."],"parameter_schema":{"properties":{"sql":{"title":"Sql","type":"string"},"max_rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Max Rows"},"fresh":{"default":false,"title":"Fresh","type":"boolean"}},"required":["sql"],"title":"QuerySubstrateInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"QuerySubstrateResponse","type":"object"},"title":"Query Substrate","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"replay_hospital_price","version":"1.5.0","description":"Replay a hospital price-proof receipt by re-running its recorded tool inputs and comparing response hash, Iceberg snapshot, plan hash, row count, status, and raw-byte source descriptor.","layer":"L2","input_schema":{"description":"Replay a previously emitted hospital price-proof receipt.","properties":{"receipt":{"additionalProperties":true,"title":"Receipt","type":"object"}},"required":["receipt"],"title":"ReplayHospitalPriceInput","type":"object"},"invariants":["bounded_fact_hospital_price_scope_v0","hospital_price_proof_receipt_replay_v0"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster"],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"description":"Replay a previously emitted hospital price-proof receipt.","properties":{"receipt":{"additionalProperties":true,"title":"Receipt","type":"object"}},"required":["receipt"],"title":"ReplayHospitalPriceInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"match","enum":["match","mismatch"],"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"},"replay_id":{"default":"","title":"Replay Id","type":"string"}},"title":"HospitalPriceReplayResponse","type":"object"},"title":"Replay Hospital Price","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"resolve_entity","version":"2.0.0","description":"Resolve any company name or ID to Vlada's canonical entity: a legal entity (le:...), a brand, an NAIC group, a CMS contract (H1234), a plan (H1234-001@2027), a Medicaid plan, a Marketplace issuer (HIOS). Matches exactly on IDs, EIN, NAIC code, CIK and names, then on names that contain every word of the text (returned as candidates, never as a match). Pass on=YYYY-MM-DD to match names as of a date. Then call describe_entity with the entity_id for its owners on a date, what it holds, and its events.","layer":"L2","input_schema":{"properties":{"text":{"title":"Text","type":"string"},"on":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"On"},"limit":{"default":25,"title":"Limit","type":"integer"}},"required":["text"],"title":"ResolveEntityInput","type":"object"},"invariants":["no_match_without_evidence","every_link_dated_and_sourced","observation_end_is_not_control_end","candidate_and_refuted_never_served"],"underlying_silver_tables_for_pinning":["vlada_ontology.l1_entity","vlada_ontology.l1_identifier","vlada_ontology.l1_edge","vlada_ontology.l1_evidence","vlada_ontology.l1_event"],"semantic_views_used":["vlada_ontology.l1_entity","vlada_ontology.l1_identifier","vlada_ontology.l1_edge","vlada_ontology.l1_evidence","vlada_ontology.l1_event"],"known_gaps":["Layer one only: no facilities, doctors, networks or PBMs (layers two to five follow on Ben's signature).","About 16% of Medicare Advantage members sit under a chain with one hop resting on CMS's parent string alone (grade B); the top parent is not in doubt, the corroborating filing is not yet attached.","Belief time (what an earlier build served) is not yet queryable; every answer carries the build it was read from.","The 233 open review-queue rows (candidate contract transfers) are not served."],"parameter_schema":{"properties":{"text":{"title":"Text","type":"string"},"on":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"On"},"limit":{"default":25,"title":"Limit","type":"integer"}},"required":["text"],"title":"ResolveEntityInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"ResolveEntityResponse","type":"object"},"title":"Resolve Entity","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"resolve_provider","version":"1.0.0","description":"Resolve a provider's identity: an NPI, an EIN, or an organisation name (+ state) -> the Medicare CCN(s) it maps to, the CCN's provider type from the CCN authority (vlada_curated.dim_provider_ccn: 101,528 CCNs across hospitals, SNFs, home health, hospice, FQHC, RHC, ASC, dialysis, IRF, LTCH), the NPPES record, the PECOS Medicare enrollment(s) with organisation name and provider type, and (include_ownership, default true) the PECOS ownership edges — owners, percentage, and the private-equity / REIT / holding-company / chain flags. Every candidate carries its match method, a confidence, and the source table per field. NPI->CCN is resolved by AGREEMENT across two bridges (provider_facility_xref, dim_hospital_external); if they disagree the answer is ambiguous_conflict with both candidates and no resolved CCN, never a guess. An unknown NPI returns unresolved with the reason, not an error. EIN and name resolution reach hospitals only (the estate's EIN-bearing roster); a shared-system EIN lists every CCN as a candidate. Each candidate carries ccn, npi, hospital_name and health_system at its top level; resolution carries resolved_npi and resolved_health_system; repeated PECOS rows are collapsed to one per enrollment.","layer":"L2","input_schema":{"properties":{"npi":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Npi"},"ein":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ein"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"include_ownership":{"default":true,"title":"Include Ownership","type":"boolean"}},"title":"ResolveProviderInput","type":"object"},"invariants":["resolve_through_measured_authorities","bridge_agreement_never_guess","is_current_only_on_m2_tables","bounded_rows","not_found_distinguished"],"underlying_silver_tables_for_pinning":["vlada_curated.dim_provider_ccn","vlada_curated.dim_provider","vlada_curated.provider_facility_xref","vlada_curated.dim_hospital_external","medicare_silver.fact_pecos_enrollment","medicare_silver.fact_provider_ownership","vlada_curated.dim_facility","vlada_curated.dim_hospital_system"],"semantic_views_used":[],"known_gaps":["NPI->CCN recall ~87% (bridge union, measured 2026-06 by the employer-book harness); individual NPIs and non-hospital organisations usually resolve to PECOS + NPPES only.","EIN and name resolution reach hospitals (dim_hospital_external) plus PECOS org names; the non-hospital rosters carry no EIN.","provider_type follows the ten CMS rosters in dim_provider_ccn; a provider type we hold no roster for is absent from the authority.","Ownership edges are keyed on PECOS enrollment_id and are self-reported; percentage can be null for indirect interests."],"parameter_schema":{"properties":{"npi":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Npi"},"ein":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ein"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"include_ownership":{"default":true,"title":"Include Ownership","type":"boolean"}},"title":"ResolveProviderInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"ResolveProviderResponse","type":"object"},"title":"Resolve Provider","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"state_expert","version":"1.2.1","description":"The callable STATE EXPERT — the data-availability + regulation X-ray for a US state. Given 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; (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. This 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. Because hospital pricing is a NATIONAL substrate, a state can show many hospitals priced even before its county map is built (e.g. MD). Stateless + state-parameterized: one runtime serves every state. To price a code across the state's hospitals, call compare_hospital_rates. SOURCE: curated hospital chargemaster + care-site registry + the state-regulation object. KNOWLEDGE (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. Pages exist for states hospital rules do not yet cover, so a found=false answer can still carry them.","layer":"L2","input_schema":{"description":"`state_code` (required, 2-letter USPS, e.g. 'CT' or 'MD').","properties":{"state_code":{"description":"2-letter USPS state code, e.g. 'CT' (fully built) or 'MD' (hospital pricing present in the national substrate; county map not yet built).","title":"State Code","type":"string"},"page":{"anyOf":[{"enum":["marketplace","medicaid"],"type":"string"},{"type":"null"}],"default":null,"description":"Return the state's knowledge page for this line in full: 'marketplace' (who regulates the individual market, what the state publishes, rate review, the issuers) or 'medicaid' (the program, its plans, procurements, rate setting, what the state publishes). Omit for the profile; every answer lists the pages and their sections under knowledge.","title":"Page"},"section":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"With page: return only the section whose heading contains this text (case-insensitive), e.g. 'Who publishes what'. The section list is under knowledge.<line>.sections.","title":"Section"}},"required":["state_code"],"title":"StateExpertInput","type":"object"},"invariants":["state_expert_v1"],"underlying_silver_tables_for_pinning":["vlada_curated.fact_hospital_chargemaster","vlada_curated.dim_care_site","vlada_curated.agg_care_site_payer_coverage"],"semantic_views_used":[],"known_gaps":["regulation_object_is_seed_not_yet_dim_state_regulation","freshness_not_yet_tracked_pending_refresh_cascade","county_map_built_for_CT_only"],"parameter_schema":{"description":"`state_code` (required, 2-letter USPS, e.g. 'CT' or 'MD').","properties":{"state_code":{"description":"2-letter USPS state code, e.g. 'CT' (fully built) or 'MD' (hospital pricing present in the national substrate; county map not yet built).","title":"State Code","type":"string"},"page":{"anyOf":[{"enum":["marketplace","medicaid"],"type":"string"},{"type":"null"}],"default":null,"description":"Return the state's knowledge page for this line in full: 'marketplace' (who regulates the individual market, what the state publishes, rate review, the issuers) or 'medicaid' (the program, its plans, procurements, rate setting, what the state publishes). Omit for the profile; every answer lists the pages and their sections under knowledge.","title":"Page"},"section":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"With page: return only the section whose heading contains this text (case-insensitive), e.g. 'Who publishes what'. The section list is under knowledge.<line>.sections.","title":"Section"}},"required":["state_code"],"title":"StateExpertInput","type":"object"},"output_schema":{"$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.0,"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"},"title":"State Expert","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"submit_query","version":"1.1.0","description":"Submit a heavy/long-running query to run OFF the request path and get a job_id back immediately, instead of blocking (and risking a timeout) on a statewide/cross-hospital scan. Arguments are validated against the target tool's own input model AT ACCEPT TIME, so a malformed submit is refused immediately (reason=invalid_arguments) instead of after you waited for the job. A POINT-LOOKUP CALL IS REFUSED, not queued: the refusal carries the direct call to make instead, with your own arguments already in it. That includes a bounded compare_hospital_rates read (one billing_code + one state), which the precomputed window answers in about a second. Pass force=true only when the SYNC door sent you here (too_large_for_sync, tool_timeout) — that route is always accepted. Poll with poll_query(job_id) and read the result with fetch_query(job_id). A refusal names the async-eligible targets and their current serving state, so you always know what this lane can run today.","layer":"L2","input_schema":{"properties":{"tool":{"title":"Tool","type":"string"},"arguments":{"additionalProperties":true,"default":{},"title":"Arguments","type":"object"},"force":{"default":false,"title":"Force","type":"boolean"}},"required":["tool"],"title":"SubmitQueryInput","type":"object"},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"properties":{"tool":{"title":"Tool","type":"string"},"arguments":{"additionalProperties":true,"default":{},"title":"Arguments","type":"object"},"force":{"default":false,"title":"Force","type":"boolean"}},"required":["tool"],"title":"SubmitQueryInput","type":"object"},"output_schema":{"$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.0,"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"}},"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":"AsyncJobResponse","type":"object"},"title":"Submit Query","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"asp_pricing_lookup","version":"1.1.0","description":"Given an HCPCS code or short-description search, returns Medicare Part B ASP quarterly payment-limit rows from drug_silver.fact_drug_asp_quarterly_v2 (is_current) with trend aggregates. Use for Part B reimbursement checks and CY 2026 IRA/MFP methodology caveats.","layer":"L2","input_schema":{"type":"object","properties":{"hcpcs_code":{"type":"string"},"short_description":{"type":"string"},"effective_period_start":{"type":"string","format":"date"},"effective_period_end":{"type":"string","format":"date"},"release_quarter":{"type":"string"},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":["drug_silver.fact_drug_asp_quarterly_v2"],"semantic_views_used":[],"known_gaps":["asp_cy_2026_mpfs_ira_mfp_layering","asp_pricing_lookup_no_match","asp_pricing_lookup_truncated"],"parameter_schema":{"type":"object","properties":{"hcpcs_code":{"type":"string"},"short_description":{"type":"string"},"effective_period_start":{"type":"string","format":"date"},"effective_period_end":{"type":"string","format":"date"},"release_quarter":{"type":"string"},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"ASP Pricing Lookup","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"excluded_prescriber_payment_screen","version":"1.2.0","description":"Given an NPI (10-digit), returns OIG LEIE exclusion status and — if excluded — any Open Payments received OR Part D prescribing activity recorded AFTER the exclusion date (and before any reinstatement). The textbook qui-tam / False Claims Act screening query. Bridges three substrate sources: dim_oig_leie (LEIE), fact_drug_payment_to_prescriber (Open Payments), fact_part_d_prescriber (Part D Prescriber-by-Drug).\n\nReturns: total post-exclusion payment dollars + Part D drug-cost exposure, broken down by year + top 5 manufacturers. Every answer carries an explicit exclusion_status (not_in_leie, excluded, or excluded_then_reinstated) beside the dollars, so a $0 result is never ambiguous: a not-in-LEIE NPI returns zero ANCHORED to the LEIE snapshot date it was checked against (leie_asserted_at), which is a different thing from an excluded prescriber who drew no post-exclusion payments.\n\nKNOWN GAPS: open_payments_publication_lag_one_year (current PY publishes June+1); part_d_puf_annual_grain_only (Part D PUF is annual not monthly — finer-grain timing requires claims data). LEIE refreshes monthly per the M-6 schedule (cycle 2).","layer":"L2","input_schema":{"type":"object","properties":{"npi":{"type":"string"},"op_lookback_years":{"type":"integer","default":10},"pdp_lookback_years":{"type":"integer","default":10},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false,"required":["npi"]},"invariants":[],"underlying_silver_tables_for_pinning":["drug_silver.dim_oig_leie","drug_silver.fact_drug_payment_to_prescriber","drug_silver.fact_part_d_prescriber"],"semantic_views_used":[],"known_gaps":["open_payments_publication_lag_one_year","part_d_puf_annual_grain_only"],"parameter_schema":{"type":"object","properties":{"npi":{"type":"string"},"op_lookback_years":{"type":"integer","default":10},"pdp_lookback_years":{"type":"integer","default":10},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false,"required":["npi"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Excluded Prescriber Payment Screen","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"formulary_churn","version":"1.0.0","description":"Given a quarter-pair (report_quarter_from, report_quarter_to) AND a formulary or plan filter, returns the formulary delta: drugs added, drugs dropped, drugs re-tiered, and optionally drugs whose control flags (prior auth / step therapy / quantity limit) changed. Diffs drug_silver.fact_drug_formulary across two SPUF report_quarters on (formulary_id, drug) keys, where a drug is its RxCUI by default (grain='rxcui'), so a manufacturer or package NDC swap of the same drug is not churn; grain='ndc' gives the package-level diff. Pass rxcui_filter=[...] to ask whether coverage of specific drugs changed.\n\nReturns: per-category row lists (cap 5000 each), aggregates (formularies_compared, n_added, n_dropped, n_tier_changed, n_control_changed, n_unchanged, churn_rate, tier_movement_distribution), truncated_by_category flags.\n\nREADING churn_rate: it is (added + dropped + re-tiered) divided by the number of drugs on the formulary in the FROM quarter — CHANGE EVENTS PER FROM-QUARTER DRUG, not a percentage. It is >= 0 and CAN EXCEED 1 (a formulary that drops everything and adds as many new drugs scores 2.0), because added drugs are not members of the denominator. The answer carries churn_rate_definition saying exactly this, the two denominators (n_in_from_quarter, n_in_to_quarter), and two bounded companions that ARE 0-1: share_dropped (dropped / FROM-quarter drugs) and share_added (added / TO-quarter drugs).\n\nUse cases: year-over-year formulary stability tracking, drop investigations for a specific drug class, IRA-era churn rate (crossing 2025 → 2026 will surface the redesign-driven churn).\n\nKNOWN GAPS: spuf_quarterly_publication_lag (CMS publishes 6 weeks after quarter end; very recent quarter changes won't show); ira_era_break_2026 (IRA Part D redesign in 2026 changed formulary structures; churn comparison crossing this boundary mixes regime changes with normal churn); formulary_churn_truncated (per-category lists capped at 5000).","layer":"L2","input_schema":{"type":"object","properties":{"report_quarter_from":{"type":"string"},"report_quarter_to":{"type":"string"},"formulary_id_filter":{"type":"array","items":{"type":"string"}},"contract_id_filter":{"type":"string"},"plan_id_filter":{"type":"string"},"include_control_changes":{"type":"boolean","default":false},"grain":{"type":"string","default":"rxcui"},"rxcui_filter":{"type":"array","items":{"type":"string"}},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false,"required":["report_quarter_from","report_quarter_to"]},"invariants":[],"underlying_silver_tables_for_pinning":["drug_silver.fact_drug_formulary","drug_silver.dim_part_d_plan"],"semantic_views_used":[],"known_gaps":["spuf_quarterly_publication_lag","ira_era_break_2026","formulary_churn_truncated","formulary_churn_no_match"],"parameter_schema":{"type":"object","properties":{"report_quarter_from":{"type":"string"},"report_quarter_to":{"type":"string"},"formulary_id_filter":{"type":"array","items":{"type":"string"}},"contract_id_filter":{"type":"string"},"plan_id_filter":{"type":"string"},"include_control_changes":{"type":"boolean","default":false},"grain":{"type":"string","default":"rxcui"},"rxcui_filter":{"type":"array","items":{"type":"string"}},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false,"required":["report_quarter_from","report_quarter_to"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Formulary Churn","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_benefit_change","version":"2.0.0","description":"The locked 2027 Medicare Advantage benefit tables in one call: what each benefit was in 2026 and what it is in 2027 for the SAME members, member-weighted from the CMS Plan Benefit Package filings and CMS September 2026 county enrollment, inside ONE product type, for the market or a parent organization, nationally, in a state or in a county. Premium, MOOP, the medical and Part D deductibles, the medical copays and coinsurance, the Part D tier cost shares, dental / OTC / hearing / eyewear / flex card dollars and offered shares, the Part B giveback and the supplemental services.\n\nARGUMENTS: product_type (required unless group_by='product_type': non-SNP HMO | non-SNP PPO | D-SNP HMO | D-SNP PPO | C-SNP HMO | C-SNP PPO | I-SNP HMO | I-SNP PPO; 'ALL' is refused, types are never pooled), geography (national | state | county; inferred from the place when omitted), state (two letters), county (the name as CMS spells it, e.g. 'Maricopa', with state) or county_ssa (five digits, e.g. '03060'), parent (the parent organization; a partial name matches, e.g. 'UnitedHealth'), plan_type (default 'ALL'; HMO | HMOPOS | Local PPO | Regional PPO), group_by (none | parent | state | county | plan_type | product_type; state needs geography national, county needs geography state), benefits ('key' default | 'all' | a comma-separated list of benefit names, listed in value.benefits), limit (rows, default 50, max 500, largest 2026 membership first).\n\nRETURNS value.summary (the market of the scope: every benefit for the scope's members) and value.rows (one per group, or per matching parent). Each row: members_2026 (every September 2026 member), members_continuing (the members on both sides of the change), plans, thin (true when the value rests on plans covering under 70% of the members or fewer than five plans) and, per benefit, {2026, 2027_same_members, change, coverage_2026, coverage_2027, 2026_all_members, unit}: 2026 is the continuing members' 2026 design, 2027_same_members those same members' 2027 design, change = 2027_same_members minus 2026; 2026_all_members is every 2026 member, context only, never one side of a change. coverage is the share of the row's members the value describes. A null value is unknown (no member filed it), never $0. Percent benefits are served 0-100. When an allowance is asked, like_for_like carries its dollars on the paired members (same form both years) with the share whose design changed form, which is a design change, never a raise or a cut.\n\nD-SNP figures are the FILED design: a full dual generally pays $0 under Medicaid; the full-dual reading is the Plan Value tool's full-dual column. Employer group plans and stand-alone Part D are not in the tables.\n\nTHE BENEFIT READING (mode = read | change | compare | drill; omit mode for the answer above). Each benefit is read as its DESIGN first (dental: a dollar maximum, the same plus a card that also pays dental, no maximum, on a card only, none), then as numbers that each carry their own denominator: value, measurable_pct (the share of the row's members the number describes; quote it), members, the simple_average across plans beside the member-weighted value, the trust tier, better_for_member, and on D-SNP rows the full_dual figure beside the filed design. benefits takes 'key', 'all', a family (allowance | card | cost_share | econ | service), a benefit (dental, otc, hearing, eyewear, card, primary_care, er, ...) or number ids such as dental:dollars_if, dental:cap_plus_card, cs:primary_care:pct_zero. years: e.g. '2024-2027' (2022-2026 each year's members; 2027 = the 2026 members followed into their 2027 plan).\n  read: the scope's cells for each year asked (include_overall=true adds a parent's labelled all-product row).\n  change: one BASE year (years='2026' = 2026 -> 2027): the same members and book vs book per number, plus value.transitions, members by from_design x to_design per benefit (exit = the plan ended with no successor), the like-for-like value change and the successor mix (renewed, restructured, crosswalked).\n  compare: parent and parent_b on the counties both serve with the product type (weight 'combined' or 'a'; overlap share printed), or contract_id against its closest contracts by footprint (precomputed).\n  drill: the plan segments behind the scope, largest first (a county, a state, or a parent nationally).\n\nSOURCE: Vlada benefit reading, edition v20261018b, from the CMS Plan Benefit Package filings, CMS county enrollment, the plan service area file and the CMS plan crosswalk.","layer":"L2","input_schema":{"type":"object","properties":{"product_type":{"enum":["non-SNP HMO","non-SNP PPO","D-SNP HMO","D-SNP PPO","C-SNP HMO","C-SNP PPO","I-SNP HMO","I-SNP PPO"],"type":"string"},"geography":{"enum":["national","state","county"],"type":"string"},"state":{"type":"string"},"county":{"type":"string"},"county_ssa":{"type":"string"},"parent":{"type":"string"},"plan_type":{"enum":["ALL","HMO","HMOPOS","Local PPO","Regional PPO"],"type":"string","default":"ALL"},"group_by":{"enum":["none","parent","state","county","plan_type","product_type"],"type":"string","default":"none"},"benefits":{"type":"string","default":"key"},"limit":{"type":"integer"},"mode":{"type":"string"},"years":{"type":"string"},"parent_b":{"type":"string"},"contract_id":{"type":"string"},"weight":{"type":"string","default":"combined"},"matrix":{"type":"boolean","default":true},"include_overall":{"type":"boolean","default":false}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":["medicare_semantic.vw_benefit_reading_cells","medicare_semantic.vw_benefit_reading_cells_sd","medicare_semantic.vw_benefit_reading_simple","medicare_semantic.vw_benefit_reading_transitions","medicare_semantic.vw_benefit_contract_match","medicare_semantic.vw_benefit_reading_matched","medicare_semantic.vw_benefit_reading_atoms"],"known_gaps":["Same-member change is 2026 continuing members against those members in 2027; members in plans that exit with no successor are in neither year, plans new in 2027 have no 2026 members.","Product types are never pooled: product_type ALL is refused.","D-SNP cost shares are the filed design; the dual-effective reading is Plan Value's full-dual column.","A null or zero weight is unknown, never $0; coverage rides beside every value.","Employer group plans and stand-alone Part D are not in the tables."],"parameter_schema":{"type":"object","properties":{"product_type":{"enum":["non-SNP HMO","non-SNP PPO","D-SNP HMO","D-SNP PPO","C-SNP HMO","C-SNP PPO","I-SNP HMO","I-SNP PPO"],"type":"string"},"geography":{"enum":["national","state","county"],"type":"string"},"state":{"type":"string"},"county":{"type":"string"},"county_ssa":{"type":"string"},"parent":{"type":"string"},"plan_type":{"enum":["ALL","HMO","HMOPOS","Local PPO","Regional PPO"],"type":"string","default":"ALL"},"group_by":{"enum":["none","parent","state","county","plan_type","product_type"],"type":"string","default":"none"},"benefits":{"type":"string","default":"key"},"limit":{"type":"integer"},"mode":{"type":"string"},"years":{"type":"string"},"parent_b":{"type":"string"},"contract_id":{"type":"string"},"weight":{"type":"string","default":"combined"},"matrix":{"type":"boolean","default":true},"include_overall":{"type":"boolean","default":false}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Benefit Change","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_contract_profile","version":"1.0.0","description":"Everything Vlada holds on one Medicare Advantage contract, or one of its plans, in ONE call: the contract (name, parent, plan type, plans and counties served), enrollment by year and state, plan economics (risk score, Part A/B payment and rebate per member per month, by year), Overall / Part C / Part D stars by rating year, every plan's premium, MOOP, deductibles and supplemental allowances with the change from the prior plan year, ALL 36 filed benefits for a plan (doctor, hospital, emergency, diagnostics, equipment, drugs, dental, vision, hearing, OTC) with history back to 2019, the largest counties with share of county, and the 15 contracts it competes with most in its own counties.\n\nARGS: contract_id (H5549, R5826, ...). Optional plan_id ('011' or 'H5549-011'): that plan's benefits come back in full with their history. Without plan_id, benefits come back for the largest `benefit_plans` individual plans offered in the benefit year (default 3, max 5). Optional sections: any of contract, enrollment, economics, stars, plans, benefits, counties, competitors (default all).\n\nSOURCE: the same nightly build that serves vladahealth.com/ma (CMS monthly enrollment, CMS Landscape and plan benefit package filings, CMS plan payment files, CMS Star Ratings); value.build names it. Benefits are the plan's FILED design; a D-SNP member's cost is usually lower after Medicaid. Employer group plans (800-series) file placeholder cost sharing and are flagged egwp. The record holds the 40 largest plans and 40 largest counties; plan_count and county_count give the full numbers. For one benefit across many plans use get_pbp_benefit; for star measures use get_stars with include_measures.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"sections":{"type":"array","items":{"type":"string"}},"benefit_plans":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["The record carries the 40 largest plans and 40 largest counties of a contract; plan_count and county_count are the full counts.","Benefits are the filed plan benefit package design (one segment's row for a segmented plan), not what a dual eligible member pays after Medicaid.","The plan crosswalk is not part of this record."],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"sections":{"type":"array","items":{"type":"string"}},"benefit_plans":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Contract Profile","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_contract_service_area","version":"0.2.0","description":"The county-level service area of Medicare Advantage contracts, month by month, from CMS's monthly MA Contract Service Area file (2006-10 on; 2022-11 was never published). Both directions: the counties a contract serves (contract_id) and the contracts serving a county (county_fips, 5 digits) or a state (state_code, 2 letters).\n\nWINDOW: report_month (YYYY-MM) or year; with neither, the newest month held (stated in value.query.report_month).\n\nRETURNS value.summary (distinct contracts, counties, contract-counties and contract-county-months; national, employer-group and partial-county counts; the months read), value.contracts (one row per contract: organization, organization type, plan type, counties served, employer-group and partial counties) and value.rows (one row per contract, county, month and flag combination: state_code, county_fips, county_ssa, county_name, eghp, partial_county, national_service_area). `limit` bounds both lists (default 100, max 2000); a truncated list carries a caveat.\n\nTHREE RULES: (1) eghp (employer-group only) and partial_county are CMS's own flags; eghp_only=true keeps employer-group rows. (2) A contract serving the whole country (National PACE and similar) is one national row with no state or county (national_service_area=true); it is never counted as a county, and a state or county filter leaves it out unless include_national=true. (3) CMS lists a contract-county twice when its plans there differ in the partial or employer flag, so count DISTINCT contract-counties, never rows; the summary already does.\n\nEach month is read at its newest CMS edition. Stand-alone Part D (PDP) service areas are a separate file and are not here.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"county_fips":{"type":"string"},"state_code":{"type":"string"},"report_month":{"type":"string"},"year":{"type":"integer"},"eghp_only":{"type":"boolean"},"include_national":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.ma_contract_service_area_v2"],"semantic_views_used":[],"known_gaps":["eghp and partial_county are CMS's own flags (parse revision 2); the revision-1 defect that read them false on every row does not apply.","National service-area rows have no state or county (national_service_area true); they are excluded from county counts and from state or county filters unless include_national is set.","A contract-county split across flag values appears on more than one row: count DISTINCT contract-counties.","CMS never published the 2022-11 file."],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"county_fips":{"type":"string"},"state_code":{"type":"string"},"report_month":{"type":"string"},"year":{"type":"integer"},"eghp_only":{"type":"boolean"},"include_national":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Contract Service Area","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_county_view","version":"1.5.0","description":"The whole Medicare Advantage picture of ONE county, over time, in one call: (1) enrollment by parent and product type each September from 2021, with CMS small-cell suppression carried as a floor and a ceiling, and the county's MA penetration where CMS holds it; (2) plan exits for every transition from 2023: continuing, departing, the five Day-One buckets, the true outcome where the crosswalk is held or the calibrated estimate range where not, parents before and parents continuing; (3) the same members' plan design this year against next (total premium, $0 premium share, MOOP, $0 Part D deductible share, D-SNP $0 cost sharing, star), at county grain where held, else the state figures under their own name with a coded note (get_landscape_benefit_change serves twelve metrics at state grain); (4) every plan sold in the county in the plan year with premium, MOOP, deductible and star, the D-SNP fields in their own columns, paged; (5) September members in contracts rated 4+ stars by rating year, with the rating-year to payment-year clock; (6) the County Volatility Index every plan year 2016-2027: per 100 members, those whose plan ended, who were moved, or whose plan made a material cut (premium +$10/month, MOOP +$500, dental max -$500 or dropped), pooled and by product type, beside the state and the nation, with the county's rank (detail=true adds the plans behind the newest year and what each changed; get_volatility_index ranks counties, states and insurers). Every tile is one row per product type with arrays over years or transitions, so the county reads over time in one call.\n\nARGUMENTS: state (two-letter) and county (the county name as CMS spells it, e.g. 'Cook', 'DuPage'; 'County' may be included or left off; a misspelling is refused naming the nearest CMS spellings), OR county_fips (five digits, e.g. '17031'), OR county_ssa (the five-digit CMS SSA state-county code, e.g. '14140', resolved to its FIPS through the CMS penetration file); year (the plan year for the plan list, default the newest Landscape year held); sections (comma-separated subset of enrollment, exits, benefit_change, plans, stars, volatility; default the first five: ask for volatility by name, e.g. sections=volatility for 'how volatile is my county'); detail: the two modes, summary (default, false: the product-type tiles, which fit one answer) and full (true: the tiles plus the parent x product type rows for enrollment and for the newest exits transition, and the plan list itself, paged); limit (rows per detail list per page, default 5, max 200) and offset (default 0), which page every detail list together, so a long page is one section at a time (sections=plans, detail=true, limit=100); include_cost_mmp (default false: industry = every product type but Cost and MMP).\n\nRETURNS value.blocks (one block per section: source, edition, the five clocks, the base, the seconds it took, its caveats, and a status of measured, substituted or unavailable with a code), value.county_by_year, value.enrollment_by_product_type, value.exits_by_product_type, value.benefit_change, value.plans_by_product_type, value.stars_exposure, value.volatility_by_year, value.volatility_by_product_type, value.summary; with detail=true also value.enrollment (parent x product type), value.exits (parent x product type, newest transition), value.plans and value.volatility_plans, each paged by limit and offset.\n\nRULES THE TOOL ENFORCES: the county is resolved by FIPS and the name key the Landscape carries is derived, never typed; the member base is H/R contracts, plans 001-799, September Y, matched to the Y Landscape by plan AND county; stand-alone Part D is never in it; D-SNP is its own product type and is never pooled; suppressed cells are carried as a floor and a ceiling, so every rollup keeps its bounds; parent is CMS's reported parent at each September and a parent's figure is the sum of its members, never a plan count; every section names its clocks.\n\nSOURCE: Vlada analysis of the CMS monthly enrollment by plan and county, the CMS MA state-county penetration file, the CMS MA/Part D Landscape files, the CMS plan crosswalk where held, and the CMS Star Ratings.","layer":"L2","input_schema":{"type":"object","properties":{"state":{"type":"string"},"county":{"type":"string"},"county_fips":{"type":"string"},"county_ssa":{"type":"string"},"year":{"type":"integer"},"sections":{"type":"string"},"detail":{"type":"boolean","default":false},"limit":{"type":"integer"},"offset":{"type":"integer","default":0},"include_cost_mmp":{"type":"boolean","default":false}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.enrollment_monthly_county_v4","medicare_semantic.vw_ma_state_county_penetration_v4","medicare_silver.fact_ma_landscape","medicare_silver.stars_ratings_summary","medicare_silver.plan_crosswalks_annual"],"semantic_views_used":["medicare_semantic.vw_enrollment_monthly_county_v3","medicare_semantic.fact_landscape_disposition_v1","medicare_semantic.fact_landscape_benefits_v2","medicare_semantic.cvi_plan_county_v4"],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"state":{"type":"string"},"county":{"type":"string"},"county_fips":{"type":"string"},"county_ssa":{"type":"string"},"year":{"type":"integer"},"sections":{"type":"string"},"detail":{"type":"boolean","default":false},"limit":{"type":"integer"},"offset":{"type":"integer","default":0},"include_cost_mmp":{"type":"boolean","default":false}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get County View","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_enrollment","version":"0.4.0","description":"Returns CMS monthly enrollment for a Medicare Advantage plan or contract: the member count, the trend over time, and, at contract level, the MA-only vs Part-D split, plus org/parent and plan type. Filter by contract_id (required) + optional plan_id (plan grain vs contract total), and optional year ('2024') or month ('2024-03'); with neither, returns the latest month plus a trailing 13-month trend. Monthly coverage back to 2006. Every row carries the year-over-year change (yoy_change / yoy_pct) vs the same month one year earlier; plan rows carry the plan's SNP class (snp_type) when applicable.\n\nRETURNS a detail payload, not a bare count: value.summary (latest_month, latest_enrollment, yoy_change / yoy_pct, ma_only_count / part_d_count, trend min/max and change over the window), value.months (the per-month trend rows), value.row_counts (matched / returned / truncated / limit) and value.query (the filters actually applied). `limit` bounds the trend rows returned (default 13 months, max 2000); a truncated list always carries a caveat.\n\nEnrollment is the SPINE every other MA metric joins to (per-member, share-weighted). SUPPRESSION is honest: CMS redacts cells under 11 enrollees, which come back as count=null with a [lower, upper] bound and suppression_reason='redacted_small_cell', never a zero, and the suppression caveat fires only when a returned month is actually redacted. A contract id that does not exist returns found=false with a not_found_reason, never a suppression story.\n\nPair with get_pbp_benefit or get_stars to weight or normalize by members. SOURCE: CMS Monthly Enrollment by Plan / by Contract.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"year":{"type":"integer"},"month":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.enrollment_monthly_plan","medicare_silver.monthly_contract_enrollment_summary"],"semantic_views_used":[],"known_gaps":["Cells under 11 enrollees are CMS-redacted: count=null with a [lower, upper] bound and suppression_reason='redacted_small_cell'.","MA-only vs Part-D split is contract-level only (omit plan_id to get it).","County / market-share grain lives in enrollment_monthly_county (612M rows); this tool serves plan + contract totals."],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"year":{"type":"integer"},"month":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Enrollment","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_hos","version":"0.2.0","description":"Returns a Medicare Advantage contract's CMS Health Outcomes Survey (HOS) rates across the four survey topics (fall_risk_management, urinary_incontinence, osteoporosis_testing, physical_activity), each with the two reported rates and the year-over-year change. Filter by contract_id (required) + optional year (defaults to the latest; report years 2019-2025).\n\nRETURNS a detail payload, not a topic count: value.topics is the per-topic row list (topic, report_year, rate1, rate2, rate3, rate1_yoy), value.summary rolls it up (topic_count, which topics reported, the highest and lowest rate1), value.row_counts carries matched / returned / truncated and value.query the filters applied. `limit` bounds the rows (default 200, max 2000).\n\nHOS is the beneficiary-survey companion to the chart-abstracted HEDIS rates and feeds several Part C Star measures. rate1/rate2 are the survey's two published rates for the topic (e.g. the share who reported the issue and the share who discussed it with a provider); see the CMS HOS documentation for exact definitions. Pair with get_stars. A contract id with no HOS rows returns found=false with a not_found_reason.\n\nSOURCE: CMS Health Outcomes Survey (HOS) Public Use File.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.hedis_hos_frm","medicare_silver.hedis_hos_mui","medicare_silver.hedis_hos_oto","medicare_silver.hedis_hos_pao"],"semantic_views_used":[],"known_gaps":["rate1/rate2 semantics are topic-specific; consult the CMS HOS documentation."],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Hos","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_hospital_quality","version":"0.1.0","description":"Returns one hospital's CMS Care Compare quality record by CCN: the overall star rating (1-5) with hospital type / ownership; every Care Compare measure for the hospital (mortality and complication rates, unplanned readmission / ED-return rates, timely and effective care, healthcare-associated infections SIRs, outpatient imaging efficiency, maternal health) with the score, CMS's compared-to-national verdict where published, denominator, confidence bounds and measurement window; the HCAHPS patient-experience summary (summary star + per-dimension star ratings and linear mean scores) for the latest reporting year the hospital has; and the HRRP excess readmission ratios per condition for the latest fiscal year (ratio > 1 = more readmissions than nationally expected). Inputs: ccn (required, 6-char CMS certification number); optional measure_group (alias: measure_source) to get ONE group's measure rows (complications_deaths | unplanned_visits | timely_care | healthcare_assoc_infections | outpatient_imaging_efficiency | maternal_health); optional limit and offset to page the measure rows (default limit 25 once detail is asked for).\n\nTHE DEFAULT CALL IS A SUMMARY: ccn alone returns the overall rating, the HCAHPS and HRRP blocks, and the measure GROUPS with a count each (summary.measure_groups: measure_count / available / not_available / vs_national per group) — NOT the ~108 measure rows, which exceed the response budget for a single hospital. Totals are still reported (summary.measure_count) and row_counts.measures names what was withheld; ask again with measure_group, or limit / offset, for the rows.\n\nRETURNS a detail payload: value.summary (facility, overall_rating with status + footnote, hcahps_summary_star, counts, measure_groups, measure_detail_mode, and a `blocks` map saying which of overall_rating / measures / hcahps / hrrp are available for THIS hospital); value.measures, value.hcahps, value.hrrp row lists. Every row carries status = available | not_available (with the CMS footnote or reason), source_table and source_vintage (asserted_at). Nothing is fabricated: a suppressed or unreported measure is not_available, never a zero; an unrated hospital reports overall_rating null with the CMS footnote. All four sources are read WHERE is_current = true. An unknown CCN returns found=false.\n\nSOURCE: CMS Provider Data Catalog (Care Compare) Hospital General Information, hospital measure files, HCAHPS, and the HRRP hospital file.","layer":"L2","input_schema":{"type":"object","properties":{"ccn":{"type":"string"},"measure_group":{"type":"string"},"measure_source":{"type":"string"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"additionalProperties":false,"required":["ccn"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.dim_hospital_quality","medicare_silver.fact_hospital_quality_measure","medicare_silver.fact_hcahps","medicare_silver.fact_hrrp"],"semantic_views_used":[],"known_gaps":["overall_rating is null for hospitals CMS does not rate (~40% of CCNs) — unrated, not 0.","score_numeric is null for suppressed / categorical / footnoted measures; the row is returned as not_available with the footnote.","HCAHPS answer-percent distribution rows are not returned (star + linear mean summary only); HRRP is the latest fiscal year only.","Measure semantics differ per measure_id; do not compare scores across unlike measures."],"parameter_schema":{"type":"object","properties":{"ccn":{"type":"string"},"measure_group":{"type":"string"},"measure_source":{"type":"string"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"additionalProperties":false,"required":["ccn"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Hospital Quality","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_landscape","version":"0.5.0","description":"Returns the CMS Landscape view of a Medicare plan: monthly premium, in-network MOOP, overall star rating, plan type, and the county/state service-area breadth. Filter by contract_id (required) + optional plan_id (1 to 3 digits, zero-padded), segment_id and year; omit plan_id to list all plans on a contract.\n\nRETURNS a detail payload, not a plan-year count: value.plans is the actual PLAN LIST, ONE ROW PER PLAN SEGMENT (report_year, plan_id, segment_id, segment_count, plan_name, org_name, parent_org_name, plan_type, category, snp_type, total_premium, total_premium_basis, premium_as_filed, consolidated_premium, part_c_premium, part_d_premium, moop_in_network, overall_star_rating, overall_star_status, service_area_county_count / state_count), sorted premium ascending so the cheapest lead; value.summary rolls it up (plan_count = distinct plans, segment_row_count, segmented_plan_count, total premium min / median / max, zero-premium count, premium basis counts, star min / max, total distinct counties); value.row_counts carries matched / returned / truncated and value.query the filters applied. `limit` bounds the row list (default 200, max 2000); a truncated list always carries a caveat.\n\nREADING THE PREMIUM. total_premium is the plan's monthly premium on one basis per row, named in total_premium_basis: 'consolidated' (CMS's Part C plus Part D figure), 'part_c_only_no_drug_coverage' (from CY2025 CMS prints the consolidated premium as 'Not Applicable' on every plan without drug coverage, so the Part C premium is the whole premium), 'part_d_only' (a PDP), or null when CMS filed no figure. CMS's own text is carried in premium_as_filed; its '$-' token (CY2014, 2015, 2019-2023) is a $0 premium, never missing. A segment is its own filed design: a segmented plan has one row per segment with its own premium and MOOP.\n\nCovers ALL plan categories (MA, PDP, SNP, MMP, Cost), 2007-2027; the CY2027 file loaded 2026-09-28. The Landscape drops ~early September, ahead of the October benefits drop, so it is the first official view of the upcoming plan year. Stars for 2013-2020 are read from CMS's text form ('3.5 Stars'); a CMS message in place of a star is carried in overall_star_status. Pair with get_pbp_benefit (benefits) for the full picture. A contract / plan / year with no Landscape rows returns found=false with a not_found_reason.\n\nSOURCE: CMS MA/Part-D Landscape source files.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"segment_id":{"type":"string"},"year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.fact_ma_landscape"],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"segment_id":{"type":"string"},"year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Landscape","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_landscape_benefit_change","version":"1.4.0","description":"What the plan design looked like for the SAME Medicare Advantage members in year Y and in year Y+1, member-weighted from the CMS Landscape files: total, Part C and Part D premiums and the $0 shares, the premium after full Extra Help, in-network MOOP and the share at or under $5,000, the Part D deductible and its $0 and standard shares, the tier-skips-deductible share, MA-PD and enhanced shares, the D-SNP $0 cost sharing, FIDE and HIDE shares, and the overall star. Both sides of a change are the SAME members: y = the Y design of the members whose plan continues in their county (same_store, Day-One) or is routed through the CMS crosswalk where that crosswalk is held (routed: continues + moved); y1 = those members' Y+1 design; change = y1 minus y. all_members_y = the Y design on every September-Y member (members_y), context only, never one side of a change. The members whose plan departs and is not yet crosswalked are in all_members_y and members_y but NOT in y, y1 or members_y1, and the row says how many.\n\nARGUMENTS: transition_year (Y, default the newest held), group_by (national | product_type | parent | state | parent_by_product | state_by_product | county; county needs state and returns one row per county of that state, each on its own members), product_type / state / parent (filters), county (filter, the county name as CMS spells it, e.g. 'Maricopa'; with product_type it cuts one county by product), metrics ('key' = the twelve headline metrics, 'all' = every metric, or a comma-separated list of metric names), weight (same_store | routed; any other value is refused by name, and routed is refused where the crosswalk is not held), include_cost_mmp (default false), limit (default 50, max 500, largest members first).\n\nRETURNS value.rows (one per group: members_y (every September-Y member), members_y1 (the same members on both sides of the change) and, per metric, {y, y1, change, all_members_y, unit}), value.summary (the national row for the same scope, the editions, the weight used) and value.metrics (the metric labels and units). Dollars are the filed monthly premium / annual MOOP or deductible in nominal dollars; pct metrics are shares of members in the metric's own domain (Part D metrics over MA-PD members, D-SNP metrics over D-SNP members).\n\nRULES THE TOOL ENFORCES: member base H/R contracts, plans 001-799, matched to the Y file by plan and county; PDP never; industry excludes Cost and MMP unless asked; D-SNP is its own product type; a change is over the same members, never a mix of two populations. Suppressed cells count as zero, so every weight is a floor.\n\nSOURCE: Vlada analysis of the CMS MA/Part D Landscape files, CMS monthly enrollment by plan and county, and the CMS plan crosswalk where held.","layer":"L2","input_schema":{"type":"object","properties":{"transition_year":{"type":"integer"},"group_by":{"enum":["national","product_type","parent","state","parent_by_product","state_by_product","county"],"type":"string","default":"national"},"product_type":{"type":"string"},"state":{"type":"string"},"parent":{"type":"string"},"county":{"type":"string"},"metrics":{"type":"string","default":"key"},"weight":{"enum":["same_store","routed"],"type":"string","default":"same_store"},"include_cost_mmp":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.fact_ma_landscape","medicare_silver.enrollment_monthly_county","medicare_silver.plan_crosswalks_annual"],"semantic_views_used":["medicare_semantic.fact_landscape_benefits_v2","medicare_semantic.fact_landscape_benefits_county_v2"],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"transition_year":{"type":"integer"},"group_by":{"enum":["national","product_type","parent","state","parent_by_product","state_by_product","county"],"type":"string","default":"national"},"product_type":{"type":"string"},"state":{"type":"string"},"parent":{"type":"string"},"county":{"type":"string"},"metrics":{"type":"string","default":"key"},"weight":{"enum":["same_store","routed"],"type":"string","default":"same_store"},"include_cost_mmp":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Landscape Benefit Change","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_landscape_exits","version":"1.2.1","description":"Members of Medicare Advantage plans that do NOT continue into the next plan year, from the Landscape disposition: every September member of year Y placed against the Y+1 Landscape file. A member CONTINUES when the same plan is sold in their county next year; otherwise they are DEPARTING, split into the five Day-One buckets the two Landscape files can see (D1 a same-named plan in the county, D2 the plan still sold elsewhere, D3 the contract still in the county, D4 the parent still in the county, D5 the parent gone). When the CMS crosswalk for Y+1 is held, each row also carries the TRUE outcome (moved, split, stranded by a service-area reduction, terminated); when it is not yet held (the newest transition) the answer carries the calibrated estimate range of members who lose their plan, from the buckets' measured rates in the held years.\n\nARGUMENTS: transition_year (Y, the September enrollment year; default the newest held, 2026 = the 2026 to 2027 transition), group_by (national | product_type | parent | state | parent_by_product | state_by_product | county; default national; county needs state and returns one row per county of that state, each with its own members base), product_type (filter, e.g. 'non-SNP HMO', 'D-SNP HMO'), state (two-letter filter; required when group_by is county), county (filter, the county name as CMS spells it, e.g. 'Cook' or 'Maricopa'; with group_by county it returns that one county), parent (filter, the CMS parent organization as reported), include_cost_mmp (default false: industry = every product type but Cost and MMP), limit (rows, default 50, max 500, largest members first).\n\nRETURNS value.rows (one per group: base_members = THE MARKET, the number to quote as 'members in the market', the base pct_departing is over; continuing, departing, pct_departing, the five buckets, and either the true_* outcomes or est_lost_low / est_lost_high; then members_september = base_members PLUS the members whose plan-county is not in the Y Landscape list or is outside the Landscape, a reconciliation figure, never the market), value.summary (the totals for the same scope, the editions, and the calibration rates used). For 'your county, 2027': group_by county, state and county, then product_type to cut it by product.\n\nRULES THE TOOL ENFORCES: the member base is H/R contracts, plans 001-799, September Y, matched to the Y Landscape by plan AND county (members whose plan-county is not listed are counted separately, never silently); stand-alone Part D (PDP) is never in it; D-SNP is its own product type and is never pooled; parent is CMS's reported parent organization at September Y, not a canonical chain across renames. Suppressed enrollment cells (under 11) count as zero, so every figure is a floor.\n\nSOURCE: Vlada analysis of the CMS MA/Part D Landscape files, CMS monthly enrollment by plan and county, and the CMS plan crosswalk where held.","layer":"L2","input_schema":{"type":"object","properties":{"transition_year":{"type":"integer"},"group_by":{"enum":["national","product_type","parent","state","parent_by_product","state_by_product","county"],"type":"string","default":"national"},"product_type":{"type":"string"},"state":{"type":"string"},"parent":{"type":"string"},"county":{"type":"string"},"include_cost_mmp":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.fact_ma_landscape","medicare_silver.enrollment_monthly_county","medicare_silver.plan_crosswalks_annual"],"semantic_views_used":["medicare_semantic.fact_landscape_disposition_v1"],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"transition_year":{"type":"integer"},"group_by":{"enum":["national","product_type","parent","state","parent_by_product","state_by_product","county"],"type":"string","default":"national"},"product_type":{"type":"string"},"state":{"type":"string"},"parent":{"type":"string"},"county":{"type":"string"},"include_cost_mmp":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Landscape Exits","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_market_share","version":"0.3.1","description":"Returns a Medicare Advantage plan's or contract's county-level enrollment and its SHARE of the local MA market: for each county, the plan's enrollees, the county's total MA enrolled and Medicare-eligible population, the MA penetration rate, the plan's share of county MA enrollment, and the year-over-year change in the plan's county enrollment. Filter by contract_id (required) + optional plan_id (plan vs contract total), optional state (2-letter, e.g. 'FL'), and optional month ('2024-03'); defaults to the latest available month.\n\nRETURNS an actual SHARE with the arithmetic disclosed, not a raw headcount: value.summary.share_pct is the footprint share, and it always ships alongside its numerator (share_numerator_plan_enrollees) and its denominator (share_denominator_county_ma_enrolled), so nobody has to trust a bare percentage. The denominator is the total MA enrollment of the counties this plan actually operates in for the month in scope, NOT the national MA market. value.counties is the per-county row list (plan enrollees, county MA enrolled, county eligibles, penetration, share_pct, yoy_change), largest first; value.row_counts carries matched / returned / truncated and value.query the resolved month. `limit` bounds the county list (default 200, max 2000).\n\nThis is the geography + competition lens; pair with get_enrollment for the plan/contract totals. Suppressed county cells (CMS redacts under 11) come back with null enrollees and null share, never zero, and the summary carries a [low, high] bound on the numerator that brackets them. A contract id with no county rows returns found=false with a not_found_reason.\n\nSOURCE: CMS Monthly Enrollment by CPSC + MA State/County Penetration.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"state":{"type":"string"},"month":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.enrollment_monthly_county_v4","medicare_silver.ma_state_county_penetration"],"semantic_views_used":["medicare_semantic.vw_enrollment_monthly_county_v3","medicare_semantic.vw_ma_state_county_penetration_v4"],"known_gaps":["County cells under 11 enrollees are CMS-redacted (null enrollees, null share).","Share = plan county enrollees / total MA enrolled in county (penetration file)."],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"state":{"type":"string"},"month":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Market Share","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_medicaid_mco_enrollment","version":"0.5.0","description":"Returns Medicaid managed-care enrollment for ONE state. HEADLINE (value.summary.tracker, value.tracker_parents, value.tracker_months): the Medicaid MCO enrollment tracker v2, the state's own monthly figure by parent for its latest 13 months, every figure graded observed (a published count), estimated (ours, with an interval) or modeled (indicative only, never in a total) and summed apart; summary.tracker.headline is the latest month that carries a value, with its basis, methods and interval, and summary.tracker.last_observed the latest observed month. parent_basis (optional): 'current' (default) rolls every month up to each plan's parent as bound today; 'dated' rolls each month up to the parent that owned the plan in that month; never mix the two in one series. Behind it: the annual CMS 'Enrollment by Program and Plan' roster (each managed-care program x plan with SEPARATE Medicaid-only, dual and total member counts and a value_status per count, plus parent organization) for the requested or latest calendar year (2016-2024); the state's TOTAL Medicaid and CHIP enrollment from the CMS monthly state report for the latest 12 reporting months (context: all delivery systems, managed care and fee-for-service, CHIP separate); and, for the four T-MSIS dashboard pilot states (AZ, MI, NV, NM), the MCO roster with county footprint and service categories; and the state's OWN monthly plan-level publication for its latest month (45 jurisdictions). Inputs: state (required, 2-letter USPS code); optional year (plan-roster calendar year, defaults to the latest the state has); optional limit; optional offset (skips that many rows of value.plans and value.monthly_plans in their served order; summary.paging.next_page is the exact next call).\n\nRETURNS a detail payload: value.summary (state, plan_year, plan_count, program_count, the SOURCE-PUBLISHED sum of plan total_enrollment where reported_numeric for the comprehensive_medical benefit scope ONLY, plus per-benefit-scope sums that must never be added together, with the count of rows that are suppressed / not reported, the latest monthly total Medicaid+CHIP / Medicaid / CHIP enrollment with its reporting_period, and a `blocks` map saying which sources have rows for this state); value.plans (one row per program x plan x region, ordered comprehensive medical first and largest first BEFORE the row cap, summary.plans_page saying how many rows and of which scope are not on the page: benefit_scope (comprehensive_medical, behavioral_health, dental, pharmacy, ltss, pace, nemt, pccm, limited_benefit, unknown) with the rule that set it, medicaid_only / dual / total each with value + value_status, parent_organization = the parent in force through Vlada's effective-dated plan identity decisions (null when no decision covers the filed name), parent_label_as_filed = the parent column as the state filed it (in Florida the plan's own label), calendar_year, source_table); value.monthly (reporting_period, total_medicaid_and_chip_enrollment, total_medicaid_enrollment, total_chip_enrollment, adult / child enrollment, revision + final flags, source_table); value.mco_roster (mco_name, plan_category, county_count, service_categories, source_table; NO enrollment number); value.monthly_plans (the state-published plan rows for the latest monthly observation_period, statewide where the state publishes statewide rows, otherwise sub-state as published, each with reported_value, value_unit, value_status, row_role and source_url; never summed into a state total; per program, statewide rows where the program publishes them, otherwise sub-state rows; each row carries parent_share_segment when it lies inside the parent-share view's basis, and summary.parent_share_reconciliation names that basis and routes to it). The ledger stores 17 states' publisher totals as plan detail: rows whose plan label reads as a total, whose label is fee-for-service (fee_for_service_not_a_plan), whose label is an eligibility, population or unassigned count (population_count_not_a_plan), whose plan label is a bare number, whose program label is a total, or whose value equals a suspected total in the same cell are served with row_role publisher_total_suspected / fee_for_service_not_a_plan / population_count_not_a_plan / plan_label_numeric_suspected / overlapping_summary_suspected / equals_publisher_total_suspected, the stored role kept in row_role_as_published, ordered after plan detail, never dropped; summary.monthly_plans_not_plans lists the page's non-plan rows in their own block; summary.monthly_plans_guard carries the rule and the counts over the whole month. Each monthly_plans row carries cell_check (source_total, sum_of_plans, plan_rows, difference, status): within one cell (one table, measure, program, breakdown and geography) the plan rows are summed, never the re-labelled rows, and set beside the publisher's own total, so a reader sees whether the plans add up; plan rows are never added across cells. A fractional value under value_unit 'members' is an average and the row says so (value_unit_note); a published 0 may be a masked small cell (WA prints 0 for 1 to 10). Every number carries its as-of period and exact source table. Nothing is recomputed or reconciled across sources: Medicaid-only + dual is not re-summed, a published 0 is reported_zero_or_suppressed (never exact zero), and the annual plan roster is a different population and grain from the monthly state total. All sources are read WHERE is_current = true (monthly: is_latest_revision = true). An unknown state returns found=false.\n\nSOURCE: state Medicaid agencies' published plan enrollment through the Medicaid MCO enrollment tracker v2 (medicare_semantic.vw_medicaid_mco_enrollment_tracker_v2_parent_state_month); CMS/Data.Medicaid.gov Medicaid Managed Care Enrollment by Program and Plan (state-reported, annual); CMS Medicaid & CHIP Application, Eligibility and Enrollment monthly state report; CMS Medicaid MCO Dashboard (T-MSIS, four pilot states); state Medicaid agencies' monthly managed-care enrollment reports (medicare_semantic.vw_medicaid_mco_enrollment_tracker_reported_observation_v6).","layer":"L2","input_schema":{"type":"object","properties":{"state":{"type":"string"},"year":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"parent_basis":{"type":"string"}},"additionalProperties":false,"required":["state"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.cms_medicaid_managed_care_plan_enrollment","medicare_silver.cms_medicaid_chip_enrollment_monthly_state","medicare_silver.fact_medicaid_managed_care"],"semantic_views_used":[],"known_gaps":["Tracker v2 headline: the latest month most states have printed lags the calendar; newer months are estimated (interval) or modeled (indicative, never in a total). Parents are today's binding, not the parent as of the month.","Plan roster is annual (2016-2024) and state-reported; plan labels and the filed parent column (parent_label_as_filed) are publisher text, not stable payer identities; parent_organization is read through the reviewed plan identity decisions and is null where none covers the filed name.","Published 0 may be exact zero or CMS confidentiality suppression under ten (reported_zero_or_suppressed) — never asserted as exact zero.","Monthly series = TOTAL Medicaid and CHIP enrollment (all delivery systems), not managed-care enrollment; CHIP is a separate column and is not inside the plan-level counts.","fact_medicaid_managed_care covers four pilot states (AZ, MI, NV, NM) and carries utilization, not enrollment; returned as a roster only."],"parameter_schema":{"type":"object","properties":{"state":{"type":"string"},"year":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"parent_basis":{"type":"string"}},"additionalProperties":false,"required":["state"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Medicaid Mco Enrollment","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_pbp_benefit","version":"0.5.0","description":"Returns Plan Benefit Package (PBP) benefit detail for an MA plan for a specific category (dental, inpatient_hospital, ER, etc.).\n\nPolymorphic — pass `category` to route to the right semantic view. All categories share the standard envelope: cost_share_string, copay_amount, coinsurance_pct, limit_text, auth_required, referral_required, network_type, max_oop_applies + category-specific extension fields (e.g., dental_sub_benefit).\n\nRequired: contract_id, plan_id, payment_year, category. The category must be one of the 35 live categories (listed below).\n\nThe response `value` is the full benefit-detail object: `rows` (every matched benefit row, with cost sharing, limits, and category extension fields), `row_count`, the resolved `category`/`human_label`/`view_fqn`, the `audit_chain` (CMS source URL + sha256 per row), and a `summary` sub-field carrying the single-row headline cost_share_string (or the row count when multiple sub-benefit rows match) for a quick read. Plus any methodology-shift caveats (e.g., 'B16 dental restructured CY2025' when querying dental for 2025+). Cross-year queries get cross-shift caveats.\n\nWhen the full answer would not fit in one response, `rows` come back compact (`row_format: \"compact\"`): fields identical on every row sit once in `row_common`, and a field absent from a row is null.\n\nLive categories are discovered from the contract registry at load time, so this list cannot drift from what the tool serves; an unknown category is refused (INVALID_INPUT) with this same list, never a failure. The 35 live categories are: ambulance, b19_combined_package, cardiac_pulmonary_rehab, clinical_diagnostic_therapeutic, combined_supplemental, dental, dme, dsnp_cost_share, emergency_urgent, health_professionals, hearing, home_health, inpatient_hospital, inpatient_psychiatric, meals, moop, optional_package, otc, outpatient_hospital, partb_rx_drugs, partd_drugs, partd_tier, partial_hospitalization, plan_deductible, plan_premium, preventive, prior_auth_referral, renal_dialysis, section_c_pos_oon, snf, ssbci, supplemental_other, supplemental_services, transportation, vision. The premium is `plan_premium` (not 'premium'), the deductible is `plan_deductible`, the out-of-pocket maximum is `moop`.\n\n`summary.value` is the one number a reader asks for: for plan_premium the monthly premium in USD; for plan_deductible the in-network annual deductible in USD (or null with the filed reason); for moop the in-network annual MOOP in USD, which on a D-SNP is the plan design before Medicaid and Extra Help, never what a dual pays. `summary.label` says which. Limits read in words (\"6 visits every year\"; 999 is CMS's unlimited sentinel and reads \"unlimited\"); the filed code is kept in `limit_text_raw`.\n\nA contract/plan/year/category combination with NO rows is REFUSED with code NO_DATA, not answered with an empty complete: the refusal states what was searched and routes to get_landscape (the plan ids that really exist for that contract and year) and names the valid categories. One view is read, so a nonexistent plan and a plan with nothing in this category cannot be told apart here; the refusal says so.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"payment_year":{"type":"integer"},"category":{"type":"string"},"segment_id":{"type":"string"}},"additionalProperties":false,"required":["contract_id","plan_id","payment_year","category"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.fact_ma_landscape","medicare_silver.pbp_mrx","medicare_silver.pbp_mrx_p","medicare_silver.pbp_mrx_ssm","medicare_silver.pbp_mrx_tier","medicare_silver.pbp_section_a","medicare_silver.pbp_section_b10_amb_trans","medicare_silver.pbp_section_b10_b19b_amb_trans_vbid_uf","medicare_silver.pbp_section_b11_dme_prosth_orth_sup","medicare_silver.pbp_section_b12_renal_dialysis","medicare_silver.pbp_section_b13_b19b_other_services_vbid_uf","medicare_silver.pbp_section_b13_other_services","medicare_silver.pbp_section_b13i_b19b_other_services_vbid_ssbci","medicare_silver.pbp_section_b13i_b19b_services_vbid_ssbci","medicare_silver.pbp_section_b14_preventive","medicare_silver.pbp_section_b14b_b19b_preventive_vbid_uf","medicare_silver.pbp_section_b14c_b19b_preventive_vbid_uf","medicare_silver.pbp_section_b15_partb_rx_drugs","medicare_silver.pbp_section_b16_b19b_dental_vbid_uf","medicare_silver.pbp_section_b16_dental","medicare_silver.pbp_section_b17_b19b_eye_exams_wear_vbid_uf","medicare_silver.pbp_section_b17_eye_exams_wear","medicare_silver.pbp_section_b18_b19b_hearing_exams_aids_vbid_uf","medicare_silver.pbp_section_b18_hearing_exams_aids","medicare_silver.pbp_section_b19a_model_test_vbid_uf","medicare_silver.pbp_section_b19b_model_test_vbid_uf","medicare_silver.pbp_section_b1a_b19a_inpat_hosp_vbid_uf","medicare_silver.pbp_section_b1a_b19b_inpat_hosp_vbid_uf","medicare_silver.pbp_section_b1a_inpat_hosp","medicare_silver.pbp_section_b1b_b19a_inpat_hosp_vbid_uf","medicare_silver.pbp_section_b1b_b19b_inpat_hosp_vbid_uf","medicare_silver.pbp_section_b1b_inpat_hosp_psych","medicare_silver.pbp_section_b20","medicare_silver.pbp_section_b2_b19a_snf_vbid_uf","medicare_silver.pbp_section_b2_b19b_snf_vbid_uf","medicare_silver.pbp_section_b2_snf","medicare_silver.pbp_section_b3_b19b_cardiac_rehab_vbid_uf","medicare_silver.pbp_section_b3_cardiac_rehab","medicare_silver.pbp_section_b4_b19b_emerg_urgent_vbid_uf","medicare_silver.pbp_section_b4_emerg_urgent","medicare_silver.pbp_section_b5_partial_hosp","medicare_silver.pbp_section_b6_home_health","medicare_silver.pbp_section_b7_health_prof","medicare_silver.pbp_section_b8_clin_diag_ther","medicare_silver.pbp_section_b9_outpat_hosp","medicare_silver.pbp_section_c","medicare_silver.pbp_section_c_oon","medicare_silver.pbp_section_c_pos","medicare_silver.pbp_section_d","medicare_silver.pbp_section_d_opt","medicare_silver.pbp_step_16","medicare_silver.pbp_step_17b","medicare_silver.pbp_step_18b"],"semantic_views_used":["medicare_semantic.vw_pbp_ambulance","medicare_semantic.vw_pbp_b19_combined_package","medicare_semantic.vw_pbp_cardiac_pulmonary_rehab","medicare_semantic.vw_pbp_clinical_diagnostic_therapeutic","medicare_semantic.vw_pbp_combined_supplemental","medicare_semantic.vw_pbp_dental","medicare_semantic.vw_pbp_dme","medicare_semantic.vw_pbp_dsnp_cost_share","medicare_semantic.vw_pbp_emergency_urgent","medicare_semantic.vw_pbp_health_professionals","medicare_semantic.vw_pbp_hearing","medicare_semantic.vw_pbp_home_health","medicare_semantic.vw_pbp_inpatient_hospital","medicare_semantic.vw_pbp_inpatient_psychiatric","medicare_semantic.vw_pbp_meals","medicare_semantic.vw_pbp_moop","medicare_semantic.vw_pbp_optional_package","medicare_semantic.vw_pbp_otc","medicare_semantic.vw_pbp_outpatient_hospital","medicare_semantic.vw_pbp_partb_rx_drugs","medicare_semantic.vw_pbp_partd_drugs","medicare_semantic.vw_pbp_partd_tier","medicare_semantic.vw_pbp_partial_hospitalization","medicare_semantic.vw_pbp_plan_deductible","medicare_semantic.vw_pbp_plan_premium","medicare_semantic.vw_pbp_preventive","medicare_semantic.vw_pbp_prior_auth_referral","medicare_semantic.vw_pbp_renal_dialysis","medicare_semantic.vw_pbp_section_c_pos_oon","medicare_semantic.vw_pbp_snf","medicare_semantic.vw_pbp_ssbci","medicare_semantic.vw_pbp_supplemental_other","medicare_semantic.vw_pbp_supplemental_services","medicare_semantic.vw_pbp_transportation","medicare_semantic.vw_pbp_vision"],"known_gaps":["PBP-PK-PRE-2010","PBP-QUARTERLY-PRE-2018"],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"payment_year":{"type":"integer"},"category":{"type":"string"},"segment_id":{"type":"string"}},"additionalProperties":false,"required":["contract_id","plan_id","payment_year","category"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get PBP Benefit","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_plan_value","version":"1.6.2","description":"Vlada Plan Value: MODELED value to the member of a Medicare Advantage plan, per member per month, for 2026 and 2027 (never a filed benefit, a bid or a paid claim). The headline is medical cost-sharing value at the expected position in each filed range + extras (the flex card valued by what the money buys) + Part D + the Part B buydown - the member premium, one figure per leg. D-SNP has two columns: the headline is the full-dual column (extras + Part D against the Extra Help comparator, medical $0) and the filed design rides beside it.\n\nTHREE MODES, chosen by the arguments.\nPLAN: contract_id (e.g. 'H0609') + plan_id (e.g. '025') [+ segment_id] -> each plan segment's value 2026 and 2027, the five legs, the range ends, the card bounds, the value without Part D, the filed design, and for a D-SNP the full-dual column, Part D against Extra Help and Medicaid's cost-sharing protection (published beside, never in a total), plus part_d_2027_basis. A contract alone lists its plan segments (largest first).\nMARKET: product_type (required; non-SNP HMO | non-SNP PPO | D-SNP HMO | D-SNP PPO | C-SNP HMO | C-SNP PPO | I-SNP HMO | I-SNP PPO; 'ALL' is refused) + geography (national | state | county; inferred from the place) + state / county (name as CMS spells it, with state) / county_ssa, optional parent (partial name matches) and plan_type (default 'ALL'), group_by (parent by default | none | state | county | plan_type | product_type) -> value.summary is the market: its levels (2026 = every September 2026 member, 2027 = those members followed to their 2027 plan) and its same-member change (members valued in both years: 2026, 2027, change), every leg; value.rows are the parents (or groups), largest first.\nRANK: rank=true with product_type and a geography -> who cut and who added most, on two bases side by side: 'same members' (member-weighted, the members followed) and 'plans on the shelf' (the simple average of the plans offered), each with its rank.\n\nHISTORY: history=true adds the earlier years of the same signed build. With a plan: each segment's value, legs, card bounds, value without Part D, filed design, outlier flag and September members for every plan year 2023-2027 (a plan that has since ended is found too). With a market (geography national or state, plan_type 'ALL', group_by parent | none | state | product_type): the levels for 2023-2026, each year on that year's own September members. Every year is in 2026 dollars: its filed design priced the way 2026 is, its dollar terms restated to 2026 by CMS's Medicare Advantage growth index; 2020 to 2022 are held back until their checks pass. History carries no same-member change, no county and no filed-range ends: year-to-year differences in the levels are two populations, not a change.\n\nlimit bounds the rows (default 25, max 500).\n\nREAD IT RIGHT: compare only inside one product type; a null is not valued, never $0; levels are not changes (the change is the same-member block); the 2027 Part D leg is final, priced on CMS's CY2027 formulary (a plan whose Part D could not be priced is labelled refused, never $0), and the value without Part D is the like-for-like reading of the other legs; the plan's ER cost is an upper bound (the ER copay charged on every visit, waiver on admission not applied; CMS convention); the card is the largest open sensitivity (quote the card bounds); 2027 is priced on the 2026 cohort, statute and dollars, a design comparison and not a forecast.\n\nSOURCE: Vlada Plan Value (build v12 = Method 1.2: the base-premium credit (D8), CMS's full copay (D4 cap off), card rule v3, stratum credibility, the SNF 3-day waiver, brochure-mid theta; D1 SSBCI eligibility 0.80 and D2 uncounted inpatient days off, served as sensitivities; the ER copay on every visit; signed 2026-11-02) from the CMS Plan Benefit Package filings, CMS county enrollment, the CMS plan crosswalk and the CMS Part D formulary files.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"segment_id":{"type":"string"},"product_type":{"enum":["non-SNP HMO","non-SNP PPO","D-SNP HMO","D-SNP PPO","C-SNP HMO","C-SNP PPO","I-SNP HMO","I-SNP PPO"],"type":"string"},"geography":{"enum":["national","state","county"],"type":"string"},"state":{"type":"string"},"county":{"type":"string"},"county_ssa":{"type":"string"},"parent":{"type":"string"},"plan_type":{"enum":["ALL","HMO","HMOPOS","Local PPO","Regional PPO"],"type":"string","default":"ALL"},"group_by":{"enum":["none","parent","state","county","plan_type","product_type"],"type":"string"},"rank":{"type":"boolean","default":false},"history":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":["medicare_semantic.vw_plan_value_plans","medicare_semantic.vw_plan_value_cells","medicare_semantic.vw_plan_value_pairs","medicare_semantic.vw_plan_value_history_plans","medicare_semantic.vw_plan_value_history_cells"],"known_gaps":["Every value is modeled value to the member, never a filed benefit, bid or paid claim.","The 2027 Part D leg is final: priced on CMS's CY2027 formulary (the October 2026 release); refused plans are labelled.","Medical: the plan's ER cost is an upper bound (the ER copay charged on every visit, waiver on admission not applied; CMS convention).","D-SNP headline is the full-dual column; the filed design rides beside it; Medicaid protection is never in a total.","Levels and the same-member change are different populations; the change is read from the pairs.","rank=true needs medicare_semantic.plan_value_shelf_v12; until it is published the rank mode refuses with recover_with rank=false.","history=true: 2023 onward, each year's filed design in 2026 dollars on 2026 law and prices; levels by year are each year's own members, not a same-member change; no county, plan type or filed-range ends before 2026."],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"plan_id":{"type":"string"},"segment_id":{"type":"string"},"product_type":{"enum":["non-SNP HMO","non-SNP PPO","D-SNP HMO","D-SNP PPO","C-SNP HMO","C-SNP PPO","I-SNP HMO","I-SNP PPO"],"type":"string"},"geography":{"enum":["national","state","county"],"type":"string"},"state":{"type":"string"},"county":{"type":"string"},"county_ssa":{"type":"string"},"parent":{"type":"string"},"plan_type":{"enum":["ALL","HMO","HMOPOS","Local PPO","Regional PPO"],"type":"string","default":"ALL"},"group_by":{"enum":["none","parent","state","county","plan_type","product_type"],"type":"string"},"rank":{"type":"boolean","default":false},"history":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Plan Value","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_quality_bonus","version":"1.0.0","description":"MA quality bonus dollars by contract or parent and payment year. For each: the star tier CMS pays on (bonus % of the benchmark and the rebate share), members, risk score, rebate, the benchmark bonus, and what the star tier is worth in revenue per member per month and per year, three ways: benefits held (rebate fixed), observed (what carriers did when a contract crossed a tier, 2015-2024), and the 4.0 cliff (4.0 over 3.5).\n\nARGUMENTS: contract_id (e.g. H5216) or parent (part of the parent organization's name, e.g. 'Humana'), group_by (contract | parent; default contract when contract_id is given, else parent), payment_year (default: every year for one contract, otherwise the newest year), limit (default 50, most members first).\n\nRETURNS value.rows: a contract row per payment year (tier, tier source and check against the tier CMS's payment file implies, members, PMPM and annual dollars), or a parent row per payment year (members, member-weighted star, bonus %, PMPM figures, annual dollars summed, contracts). value.summary carries the scope and which years are measured and which are modeled.\n\nRULES THE TOOL ENFORCES: rating year Y sets the bonus paid in payment year Y+1 (PY2028 uses the RY2027 stars) and every row names both; PY2025-2028 are modeled (period 'forward') and labeled; new contracts of an existing parent take the parent's member-weighted star, not 3.5; all of MA is priced (individual, employer group and regional PPO) and the share not priced is shown; a parent row weights PMPM by members priced and sums dollars.\n\nSOURCE: CMS MA ratebooks, plan payment files (average payment, risk score, rebate), Rate Announcements, Star Ratings and monthly enrollment, through Vlada's QBP financial chain (audited twice; method: STARS-QBP-FINANCIAL-CHAIN).","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"parent":{"type":"string"},"group_by":{"type":"string"},"payment_year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.stars_ratings_summary","medicare_silver.ma_plan_payment_part_c_v2"],"semantic_views_used":["medicare_semantic.stars_qbp_financial_v4"],"known_gaps":["The paid bonus for very small and new-parent contracts follows CMS's stated policy and is not verifiable from public data (under 1.5% of members)."],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"parent":{"type":"string"},"group_by":{"type":"string"},"payment_year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Quality Bonus","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_service_line_prices","version":"1.0.0","description":"A market's or a hospital's negotiated prices across a whole SERVICE LINE in ONE call: GI endoscopy, MRI, CT, cardiology, orthopedics, maternity, lab, and the rest of CMS's 70 shoppable services grouped the way buyers shop. For each code: how many hospitals price it, the market median (median of hospital medians), the 25th to 75th percentile, the low and high, and the multiple of Medicare. For each hospital: its price per code and a service-line index (its typical multiple of Medicare across the line), ranked low to high.\n\nARGS: service_line (call with service_line='list' to see every line and its codes) or codes (up to 30 CPT/HCPCS or MS-DRG). state (2 letters, required: prices are stored by state). Optional: hospitals (up to 25 CCNs) or cbsa (CMS's wage-index CBSA or metro division: Miami 33124, Houston 26420) to narrow the market; line_of_business (commercial default, medicare_advantage, medicaid, exchange, unspecified); billing_class (institutional default = the facility price; professional = the physician fee); limit (hospitals listed, default 25, max 100).\n\nRULES the tool applies: posted negotiated DOLLAR rates the comparability screen calls real (never a percent of charges); one median per method (case rate, fee schedule, per diem never mixed); line of business never pooled; a DRG is a whole inpatient stay, a CPT code one procedure. These are prices hospitals post, not paid claims. For one code in depth (per payer, methodology detail) use compare_hospital_rates.","layer":"L2","input_schema":{"type":"object","properties":{"service_line":{"type":"string"},"codes":{"type":"array","items":{"type":"string"}},"state":{"type":"string"},"hospitals":{"type":"array","items":{"type":"string"}},"cbsa":{"type":"string"},"line_of_business":{"type":"string"},"billing_class":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":[],"known_gaps":["Prices are what hospitals post in their price-transparency files, not paid claims.","Hospitals that post a code only as a percent of charges or with an unclear method are left out of that code.","The service-line index compares hospitals on the codes each prices; coverage says how many of the line's codes that is."],"parameter_schema":{"type":"object","properties":{"service_line":{"type":"string"},"codes":{"type":"array","items":{"type":"string"}},"state":{"type":"string"},"hospitals":{"type":"array","items":{"type":"string"}},"cbsa":{"type":"string"},"line_of_business":{"type":"string"},"billing_class":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Service Line Prices","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_star_benchmark","version":"1.0.0","description":"How a Medicare Advantage contract performs on the Star measures against the market, its peers, its competitors and CMS's cut points, over time. Two views in one answer. FAMILIES: for each measure family (all measures, HEDIS, HOS, CAHPS, pharmacy, complaints and leaving, appeals, call center, plan reporting) and each rating year, the contract's actual performance % (CMS-weighted mean of its measure scores; lower-is-better rates counted as their complement, so 10% readmitted = 90%; complaints per 1,000 and improvement scores are counted, not averaged), the 4-star line over exactly the measures it was scored on, and its weighted star; beside the market (member-weighted and one contract one vote), a cohort (default: its dominant product in its dominant state, e.g. D-SNPs in NY), its peer class (national carrier, Blue Cross Blue Shield plan, Kaiser, provider-sponsored, regional plan, MA-focused entrant) and the average of its five nearest competitors. MEASURES: for the latest rating year, every measure's score, star, CMS message where there is no score, the 2-5 star cut points, the market mean (members and contracts), median and middle half, the cohort mean, the gap to the market (positive = better, direction-aware), the percentile among MA contracts, and each competitor's score.\n\nARGUMENTS: contract_id (required, H or R contract, e.g. H5549), rating_year (default the newest held), years (1-13, default 5), cohort (one of product_state, product, peer_class, parent, peer_class_product, cai_group, size_band, star_band, state, org_type; default product_state), family (optional: restrict the measures view to one family, e.g. hedis), limit (measure rows, default 60).\n\nRETURNS value.summary (contract, rating year, parent, peer class, product, state, members, the cohort used, the five competitors with their parents and shared-county members), value.families (one row per family per year) and value.measures (one row per measure, latest year).\n\nRULES THE TOOL ENFORCES: every number is read from the stored benchmark tables, never averaged at call time; a score belongs to the whole contract, so a contract sits in the one product and state holding most of its members; text cells (plan too small, not enough data) are counted and never imputed; CAHPS cut points are approximate because CMS also tests significance; stand-alone drug plans are a separate market and are not included.\n\nSOURCE: CMS Part C and D Star Ratings data tables and CMS monthly enrollment, through Vlada's measure benchmark engine (stars_measure_benchmark@1.0.0).","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"rating_year":{"type":"integer"},"years":{"type":"integer"},"cohort":{"type":"string"},"family":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.stars_ratings_measure","medicare_silver.stars_ratings_summary"],"semantic_views_used":["medicare_semantic.stars_measure_benchmark_v2","medicare_semantic.stars_measure_benchmark_contract_v2","medicare_semantic.stars_measure_benchmark_category_v2","medicare_semantic.stars_measure_benchmark_category_contract_v2","medicare_semantic.stars_measure_benchmark_competitor_v2"],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"rating_year":{"type":"integer"},"years":{"type":"integer"},"cohort":{"type":"string"},"family":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Star Benchmark","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_star_decomposition","version":"1.5.2","description":"How a contract's star is built, and what moves it to the next line. For one Medicare Advantage contract and rating year: for the Overall, Part C and Part D summaries, the raw score (the weighted mean of the measure stars), the categorical adjustment (CAI), the reward factor, the score before rounding, the published star and the recomputed one, the cushion above the line the star was earned at and the gap to the next half-star line (and to 3.75, which rounds to 4.0). Then every measure: score, star, weight, direction, the next star's cut point and the distance to it in the measure's own units, and what one more star on it adds to each summary's raw score; plus the shortest list of one-star gains that closes the gap to the next line.\n\nARGUMENTS: contract_id (required, e.g. H5216), rating_year (default the newest held for the contract), limit (measure rows, default 60).\n\nRETURNS value.summary (contract, rating_year, pays_in, parts: one block per summary with its decomposition, gaps and path) and value.measures (one row per measure).\n\nRULES THE TOOL ENFORCES: the arithmetic is CMS's (the raw score over the measure set CMS used, picked so the weights add up to the recompute engine's total; the Overall leaves out the two Part D measures that duplicate Part C); one more star adds weight / total weight to the raw score; the path holds the CAI and the reward factor constant and says so; distances are in the measure's own units and direction (for a lower-is-better measure the score must fall); survey (CAHPS) cut points are approximate, because CMS also tests significance and reliability; improvement measures have no cut point. The recomputed star is the engine's, the published star is CMS's; where they differ the row says why.\n\nFLOOR BANDS: where CMS printed NA for a measure's lowest star bands (some measures in RY2015 and RY2018-2021), every score earns at least that star; the measure's floor_cut says so and it cannot be lost.\n\nSOURCE: CMS Part C and D Star Ratings Data Tables and Technical Notes, through Vlada's recompute engine, which reproduces 99.03% of the summary stars CMS published (RY2015-2027) exactly: 18,499 of 18,680.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"rating_year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.stars_ratings_measure","medicare_silver.dim_stars_measures","medicare_silver.stars_ratings_summary","medicare_silver.stars_cai"],"semantic_views_used":["medicare_semantic.stars_summary_recomputed_v10","medicare_semantic.dim_stars_measure_identity_v7"],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"rating_year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Star Decomposition","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_star_risk","version":"4.0.0","description":"Star Risk: odds a star falls, holds or rises next year. For one Medicare Advantage contract and origin rating year, for the Overall, Part C and Part D summaries, scored on the forecast year's own rules (the final rule's measure set and weights, named in the answer): Down / Same / Up for next year's star, the chance it falls below this year's star (chance to drop), the chance it lands below 4.0 (the quality bonus line; for a contract at 4.0 the same event and the same number as dropping, for one at 3.5 one minus the chance of rising) and the chance it rises (Upside), each with a status saying what it is worth. The Overall headline is Release 2r: a blend of Vlada's simulation (70%, Engine 4g) and a statistical model of the outcome with benefit and growth changes (30%), both calibrated on every year before the forecast year; the simulation's own odds ride beside it, labeled. Also: the expected star and its distribution (simulated), Star Distance (typical years of movement between the score before rounding and the line it earned), the raw score and the reward factor apart (and the chance the reward factor drops), three layers of distance (each measure to its own line, a cut point or for survey measures a modeled effective line; the score before rounding to its half-star lines; the raw mean and spread to the reward factor's thresholds), the Effective Star Cushion and Reach (descriptive), the cheapest sets of measure gains that reach the next half star (up paths), the per-contract Focus list (context) and the protect list (measures with the fewest score points above the line that keeps their star). With parent instead: the parent organization's book, the measures where contracts that improved moved up a star more often (expected members gaining a star, contracts helped; the top 3 are the held-out tested list), its protect list, and each of its contracts' Down / Same / Up.\n\nARGUMENTS: contract_id (e.g. H5216; H or R contracts, employer direct E contracts are not scored) or parent (a parent organization name such as Humana, or a contract id to use its parent); exactly one. part (Overall, C or D; default all three; contract only), rating_year (the origin rating year; default the newest scored), limit (rows, default 60).\n\nRETURNS for a contract value.summary (contract, rating_year, forecast_year, engine version and runs, the headline model, the rule set, parts: one block per summary, each probability with a _status, down_same_up, and the simulation's own odds under simulation) and value.measures (one row per measure: star, weight this year and next, removed next year, weight share, distances down and up in score points and in typical years, the line they are measured to, lift per typical year); for a parent value.summary (parent, book, focus, protect) and value.contracts (each contract's stars and odds).\n\nWHAT EACH NUMBER IS WORTH, as the answer says: on 2024-2027 (years read while the engine was built; RY2028 is the clean test), Release 2r's chance to drop ranks contracts well (AUC 0.771) and is sharper than history (Brier skill +0.079, 90% interval +0.058 to +0.101, against +0.032 for the previous model); its odds are close to calibrated (slope 1.08) but run about 3 points high on average (35.6% predicted, 32.8% actual); by origin star it predicted 14% Down for 3.0 contracts against 10% actual, 44% for 4.0 against 41%, 55% for 4.5 against 49% and 57% for 5.0 against 65%; a chance above 90% is shown as over 90% (only 5 such cases in history); a year-wide shock can move every contract together; below 4.0 is tested for contracts within half a star of the line (skill +0.100) and is context further from it; Upside is tested (from 3.5 it is the chance of reaching 4.0); Down / Same / Up is tested as one forecast; the simulation's own odds are shown only for comparison; Part C and Part D are simulated shares, uncalibrated and untested; the expected star is simulated and runs low; the parent focus list is an association tested on held-out years (top 3 only), never a promise of a star; the per-contract focus list did not pass its test and is context only; the protect list is a ranking rule, not a tested prediction, and never lists a measure CMS removes next year; slip paths are not served; the Effective Star Cushion and Reach are descriptive, never predictive; where the path engine does not reproduce CMS's published star its paths are flagged untrusted. Every number is a model forecast, not an observed rating.\n\nSOURCE: CMS Part C and D Star Ratings Data Tables, Technical Notes, cut points and the forecast year's final rule, through Vlada's Star Risk engine (simulation on CMS's exact summary arithmetic, calibrated on every earlier year, blended with a statistical model fitted on every earlier year, judged on 2024-2027 and graded on RY2028 in October 2027).","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"parent":{"type":"string"},"part":{"type":"string"},"rating_year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.stars_ratings_measure","medicare_silver.stars_ratings_summary","medicare_silver.stars_cai"],"semantic_views_used":["medicare_semantic.stars_risk_score_v6","medicare_semantic.stars_risk_focus_v6","medicare_semantic.stars_risk_parent_focus_v6"],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"parent":{"type":"string"},"part":{"type":"string"},"rating_year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Star Risk","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_stars","version":"0.8.1","description":"Returns a Medicare Advantage contract's CMS Star Ratings: the Overall, Part C, and Part D summary stars for a rating year, each with the year-over-year change vs the prior year. Set include_measures=true to also get the full per-measure breakdown (measure name, identity key, part, domain, weight, direction, the raw value and its star, the 4-star line, and the star's YoY change) so you can see exactly which measures moved the rating. The prior-year star is matched by MEASURE IDENTITY through the Stars measure spine, never by code (CMS renumbered 27 of 33 Part C codes for RY2026); prior_year_measure_id names the code the prior star was filed under. Filter by contract_id (required) + optional year (the rating_year, defaults to the latest) + optional limit (max measure rows returned). Rating years 2012-2027 (RY2027 is CMS's final October 2026 release). The answer is a detail payload: the headline stars sit in value.summary, the part rows in value.summary_parts, the measure rows in value.measures.\n\nStars drive the quality-bonus payment and rebate, so this sits directly upstream of the plan economics (payment and MLR) and is reported at the CONTRACT level (no plan_id).\n\nScores are served at the precision CMS publishes (float32 storage noise is removed on the wire). Each measure row's four_star_ladder names the cut point ladder its four-star line came from: CMS calculates MA-PD and PDP Part D cut points separately, so an MA contract (H, R) reads the MA-PD ladder and a stand-alone drug plan contract (S) the PDP ladder; ALL is a ladder CMS published for every organisation (Part C).\n\nRESTATED OVERALL. CMS restated 50 contracts' RY2026 Overall rating on July 22, 2026 (after the Clover Health ruling) without changing any measure star, so for those contracts the measure breakdown reflects the original calculation and can round to a different star than the served Overall. The answer says so in a caveat and names the original value in summary.overall_restated_from (summary.overall_restated_from_text carries CMS's text when the original was a message such as 'Not enough data available').\n\nFLOOR BANDS. Where CMS printed NA for a measure's lowest star bands (some measures in RY2015 and RY2018-2021) the measure row names the lowest band CMS printed in floor_star and floor_note.\n\nSOURCE: CMS Star Ratings (summary + measure-level) and the Vlada measure spine medicare_semantic.dim_stars_measure_identity_v7.","layer":"L2","input_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"year":{"type":"integer"},"include_measures":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.stars_ratings_summary","medicare_silver.stars_ratings_measure","medicare_silver.dim_stars_measures"],"semantic_views_used":["medicare_semantic.dim_stars_measure_identity_v7"],"known_gaps":["Stars are contract-level (no plan_id).","Measure set + weights are methodology-versioned per rating_year; a measure retired or added between years has no YoY counterpart (null change)."],"parameter_schema":{"type":"object","properties":{"contract_id":{"type":"string"},"year":{"type":"integer"},"include_measures":{"type":"boolean","default":false},"limit":{"type":"integer"}},"additionalProperties":false,"required":["contract_id"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Stars","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_stars_cutpoints","version":"0.6.1","description":"Returns CMS-published per-measure star-level cut points (the threshold a contract must reach for stars 2 to 5) for a rating_year, read through the Stars measure spine so a measure keeps its identity across years even when CMS renumbers its code (27 of 33 Part C codes moved for RY2026).\n\nTWO SHAPES. Pass measure_id (that year's code, e.g. C09; a trailing ':' as stored is accepted) or measure_identity_key (the stable key, e.g. 'c:controlling_blood_pressure') for ONE measure: value.measure carries the identity, the star_2 to star_5 thresholds with their ops, the prior and next year's code and the ladder direction; value.cutpoints carries the raw CMS rows; include_history=true adds value.history, the same identity's ladder in every rated year (cut point drift). With neither, value.measures is a paged index of the year's measures (limit, offset; default 50 rows) and the answer names the per-measure call.\n\nLADDER. CMS calculates MA-PD and PDP Part D cut points separately. The header (value.measure and the index rows) reads the ladder for org_subtype: MA-PD by default (the Medicare Advantage question), PDP for a stand-alone drug plan question; cutpoint_org_subtype names the ladder read, and it is ALL only where CMS published one ladder for every organisation (Part C). org_subtype (MA-PD | PDP | ALL) and star_level (1-5) also filter the raw rows.\n\nUse cases: 'what is the 4-star line for Controlling Blood Pressure in RY2027?'; 'how did that line move since RY2024?'; 'how much would contract H1234 need to improve to reach 5 stars on D08?'.\n\nSOURCE: CMS Tech Notes Attachment H (Tukey-aware threshold tables) for RY2024+, Attachment H pre-Tukey for RY2017-RY2023, pre-fixed cut points for RY2015-RY2016. RY2027 is CMS's final release (the 2027 Data Tables, 2026-10-08); the plan-preview rows it replaced stay readable as superseded (is_current = false). Spine: medicare_semantic.dim_stars_measure_identity_v7 (tools/ma_brain/stars_measure_spine_publish.py), whose direction flag agrees with CMS's own cut point ladder in every rated year.\n\nFLOOR BANDS. Where CMS printed NA for the lowest star bands (some measures in RY2015 and RY2018-2021), the band's op is 'floor' and its threshold is null: every score reaches it. floor_star names the lowest band CMS printed (3 stars on every MA floor ladder, e.g. RY2019 Kidney Disease Monitoring: no 1- or 2-star band, 3 stars at 87% or more; RY2020 Complaints about the Health Plan: 3 stars above 1.29).\n\nHOLDINGS ARE NAMED, NEVER IMPLIED. When a rating year holds only ONE Part D ladder the answer says so and which population it is for. A measure with no cut point rows in a year is reported as not held in this edition, with the years held named; CMS publishes cut points every year. Thresholds are served at the precision CMS publishes (float32 storage noise is removed on the wire).","layer":"L2","input_schema":{"type":"object","properties":{"rating_year":{"type":"integer"},"measure_id":{"type":"string"},"measure_identity_key":{"type":"string"},"org_subtype":{"type":"string"},"star_level":{"type":"integer"},"include_history":{"type":"boolean","default":false},"limit":{"type":"integer"},"offset":{"type":"integer"}},"additionalProperties":false,"required":["rating_year"]},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.stars_cutpoints","medicare_silver.dim_stars_measures"],"semantic_views_used":["medicare_semantic.dim_stars_measure_identity_v7"],"known_gaps":["stars_methodology_pdf_uncited"],"parameter_schema":{"type":"object","properties":{"rating_year":{"type":"integer"},"measure_id":{"type":"string"},"measure_identity_key":{"type":"string"},"org_subtype":{"type":"string"},"star_level":{"type":"integer"},"include_history":{"type":"boolean","default":false},"limit":{"type":"integer"},"offset":{"type":"integer"}},"additionalProperties":false,"required":["rating_year"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Stars Cutpoints","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_stars_rollup","version":"1.2.0","description":"MA Star Ratings by parent, product type or state, year over year. For a rating year against the year before: members in rated and unrated contracts, the member-weighted Overall star, the share of members (and of contracts) at 4 stars or more, and members by Overall star. Optionally the weighted measure star for a measure group, like for like.\n\nARGUMENTS: rating_year (default the newest with Overall stars), compare_year (default rating_year minus 1), group_by (national | parent | product_type | parent_by_product | state | state_by_product), parent (filter: part of the parent organization's name, e.g. 'UnitedHealth'), product_type (filter: nonsnp_hmo | nonsnp_ppo | dsnp_hmo | dsnp_ppo | csnp_hmo | csnp_ppo | isnp | other), state (filter: two-letter code), measure_group (optional: all | part_c | part_d | patient_safety | domain:<CMS domain code, e.g. HD3 or DD4> | source:<CMS data source, e.g. HEDIS, CAHPS, HOS, PDE> | measure:<measure identity key, e.g. c:controlling_blood_pressure>), limit (default 50, largest rated members first).\n\nRETURNS value.rows (one per group), each with members_rated, members_unrated, contracts_rated, contracts_unrated, pct_members_4plus, wtd_avg_star, pct_contracts_4plus, members_by_star, prior (the same fields for compare_year) and change; with measure_group, a measure_group block {measures, contracts, wtd_measure_star, wtd_measure_star_prior, change}. value.summary is the national row for the same filters, with each year's weight month.\n\nRULES THE TOOL ENFORCES: rating year Y is weighted by December of the payment year (Y+1), or the latest month when that December is not published, and says which (the certified house convention); the parent is the enrollment file's parent at the weight month; stand-alone drug plans are out; unrated contracts are counted apart, never as zero stars; product types are the fixed buckets (non-SNP, D-SNP, C-SNP by HMO and PPO; I-SNP; other), never pooled; a star belongs to the contract, so a product type or state row weights the contract's star by its members there; a measure group change compares the same contracts, measures, weights (the rating year's) and members, and leaves out new measures, re-specified measures and the improvement measures. Measure stars are CMS's normalization; raw scores are never averaged across measures.\n\nSOURCE: CMS Part C and D Star Ratings Data Tables and CMS monthly enrollment (contract, plan, SNP and county files).","layer":"L2","input_schema":{"type":"object","properties":{"rating_year":{"type":"integer"},"compare_year":{"type":"integer"},"group_by":{"type":"string","default":"national"},"parent":{"type":"string"},"product_type":{"type":"string"},"state":{"type":"string"},"measure_group":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":["medicare_silver.stars_ratings_summary","medicare_silver.stars_contracts","medicare_silver.stars_ratings_measure","medicare_silver.dim_stars_measures","medicare_silver.monthly_contract_enrollment_summary","medicare_silver.enrollment_monthly_plan","medicare_silver.enrollment_monthly_county"],"semantic_views_used":["medicare_semantic.dim_stars_measure_identity_v7","medicare_semantic.vw_snp_data_v3"],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"rating_year":{"type":"integer"},"compare_year":{"type":"integer"},"group_by":{"type":"string","default":"national"},"parent":{"type":"string"},"product_type":{"type":"string"},"state":{"type":"string"},"measure_group":{"type":"string"},"limit":{"type":"integer"}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Stars Rollup","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_volatility_index","version":"1.0.0","description":"The County Volatility Index, ranked across counties, states or insurers: per 100 members of individual Medicare Advantage plans the September before a plan year, those whose plan ended, who were moved into another plan by their insurer, or whose plan stayed and made a material cut (premium up $10+ a month, in-network MOOP up $500+, comprehensive dental max down $500+ or dropped). Use it for 'most volatile counties in Texas for 2027', 'which insurers' members faced the most change', 'regular PPOs vs HMOs', 'which counties settled since 2023'. For ONE county's full picture (its index every year, by product type, its rank and the plans behind it) use get_county_view with sections=volatility.\n\nARGS: level (county default, state, parent = CMS parent organization the September before); state (two letters, narrows counties or parents to one state); product (all default, or regular_hmo, regular_ppo, regular_other, dsnp_hmo, dsnp_ppo, csnp_hmo, csnp_ppo, isnp_hmo, isnp_ppo); year (plan year 2016-2027, default 2027); compare_year (default 2023; 'none' to omit); order (most default, or least); min_members (default 250; counties also need 2+ plans to be ranked); limit (default 25, max 200) and offset.\n\nRETURNS value.rows (rank, name, members, plans, index, plan ended / moved / material cut / gains per 100, the compare-year index and the change), value.scope (the same figures for the whole state or nation), value.nation, value.summary (how many entities passed the size rule).\n\nRULES THE TOOL ENFORCES: every year is plans as filed against the prior September's members, what members face, not outcomes; before 2021 only the exit part (plan ended + moved) exists and is never called the index; rates are sums of members, county indexes are never averaged; small counties are counted in totals but never ranked; special-needs plans are their own product types; plans that only followed CMS's MOOP ceiling are their own line, never a cut.\n\nSOURCE: Vlada analysis of the CMS plan crosswalk, Landscape, plan benefit filings and monthly enrollment by plan and county (County Volatility Index v4, Report 2).","layer":"L2","input_schema":{"type":"object","properties":{"level":{"type":"string"},"state":{"type":"string"},"product":{"type":"string"},"year":{"type":"integer"},"compare_year":{},"order":{"type":"string"},"min_members":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer","default":0}},"additionalProperties":false},"invariants":[],"underlying_silver_tables_for_pinning":[],"semantic_views_used":["medicare_semantic.cvi_plan_county_v4"],"known_gaps":["Every year is plans as filed against the prior September's members: what members face, not where they go.","The benefit part is a floor: over-the-counter and Part B giveback cuts are not counted.","Benefits are scored from 2021; earlier years carry plans ending and members moved only."],"parameter_schema":{"type":"object","properties":{"level":{"type":"string"},"state":{"type":"string"},"product":{"type":"string"},"year":{"type":"integer"},"compare_year":{},"order":{"type":"string"},"min_members":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer","default":0}},"additionalProperties":false},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Get Volatility Index","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"medicare_allowed","version":"0.1.0","description":"Returns the Medicare allowed amount for ONE billing code (CPT/HCPCS, or an MS-DRG for inpatient) from every Medicare fee schedule that prices it: PFS (professional, national non-facility), OPPS Addendum B (hospital outpatient APC), ASC, CLFS (lab), and IPPS (national DRG amount). Inputs: billing_code (required); optional care_class to pick the setting that fits a site (02_asc, 03_outpatient, 04_urgent_care, 05_imaging, 06_lab, 07_dialysis — the same preference table the care-site price bridge uses for its Medicare floor); optional setting to return one schedule only (PFS_non_facility | OPPS_APC | ASC | CLFS | IPPS_MSDRG_national); optional medicare_year to PIN a schedule vintage (4-digit year; omit it and the LATEST edition held for the chosen schedule is served — an older vintage is never returned unless you pin it); optional limit.\n\nRETURNS a detail payload: value.medicare_year and value.setting state the vintage and schedule actually served; value.summary carries the PREFERRED row for the requested care_class (medicare_allowed, medicare_source, medicare_year, billing_class), the latest year held per schedule (latest_year_by_schedule) and whether the year was pinned or resolved (medicare_year_selection), plus the count of schedules that price the code; value.settings lists EVERY schedule row for the code with what it is (fee_schedule, professional vs facility component, site, national basis, locality_adjusted=false, source_table, medicare_year vintage). Every number is NATIONAL — no GPCI / wage-index localisation is applied, and PFS is the NON-FACILITY (office) professional rate. A code priced on no schedule returns found=false ('not priced on these Medicare schedules', never $0). Reads the latest available edition per schedule (vlada_curated.vw_medicare_benchmark_effective per schedule, so an ASC rate is listed beside the OPPS rate for the same code; the underlying M-2 fact tables are read WHERE is_current).\n\nSOURCE: CMS PFS RVU + conversion factor, OPPS Addendum B, ASC addendum, CLFS, IPPS Table 5 + base rates.","layer":"L2","input_schema":{"type":"object","properties":{"billing_code":{"type":"string"},"care_class":{"type":"string"},"setting":{"type":"string"},"medicare_year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["billing_code"]},"invariants":[],"underlying_silver_tables_for_pinning":["vlada_curated.vw_medicare_benchmark","vlada_curated.vw_medicare_benchmark_effective","medicare_silver.fact_pfs_rvu","medicare_silver.fact_opps_addendum_b","medicare_silver.fact_asc_addendum","medicare_silver.fact_clfs_national_rate"],"semantic_views_used":[],"known_gaps":["National amounts only: no GPCI (PFS) or wage-index (OPPS/ASC/IPPS) localisation.","PFS is the non-facility (office) professional rate; the facility-setting professional rate is not served.","DMEPOS / anesthesia / ESRD schedules are not loaded; a code absent from every served schedule is 'not priced here', not $0."],"parameter_schema":{"type":"object","properties":{"billing_code":{"type":"string"},"care_class":{"type":"string"},"setting":{"type":"string"},"medicare_year":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false,"required":["billing_code"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Medicare Allowed","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"pbm_compensation_rollup","version":"2.0.0","description":"Sums Form 5500 Schedule C direct + indirect compensation for a named PBM across one or more plan years. Every aggregate runs SERVER-SIDE in SQL over the whole matching population; the per-provider-name and per-plan-year rows the total is made of ride the answer, and each alias spelling carries its own measured attribution. M-6 alias chain resolves OptumRx -> OPTUMRX + OPTUM RX + Catamaran (post-2015 acquisition), Express Scripts -> ESI / ESI MAIL PHARMACY, CVS Caremark -> all variants; a name that is NOT a registered alias_form says so instead of silently searching one literal string.\n\nReference demo (re-measured live 2026-08-01): OptumRx plan year 2023 -> $1,461,686,909 direct comp across 295 plan-filings and 295 provider rows, attributed OPTUMRX $1,036,556,258 / OPTUM RX $425,110,391 / Catamaran $20,260.","layer":"L2","input_schema":{"type":"object","properties":{"pbm_name":{"type":"string"},"year_min":{"type":"integer","default":2009},"year_max":{"type":"integer","default":2024},"detail_limit":{"type":"integer","default":25},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false,"required":["pbm_name"]},"invariants":[],"underlying_silver_tables_for_pinning":["drug_silver.fact_form5500_service_provider","drug_silver.fact_form5500_filing"],"semantic_views_used":[],"known_gaps":[],"parameter_schema":{"type":"object","properties":{"pbm_name":{"type":"string"},"year_min":{"type":"integer","default":2009},"year_max":{"type":"integer","default":2024},"detail_limit":{"type":"integer","default":25},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false,"required":["pbm_name"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Pbm Compensation Rollup","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"recall_spend_window","version":"2.0.0","description":"Given an FDA-assigned recall_number, returns recall metadata plus Medicare Part D and Medicaid SDUD federal spend on the recalled drug during the recall window (initiation -> termination), summed SERVER-SIDE with per-year Part D rows and per-NDC Medicaid rows riding the answer. The recall source carries NO NDC (openfda_product_ndc_first is NULL on all 17,830 current rows), so the Medicaid leg reaches NDCs through dim_drug on the openFDA product name and says so. Each leg reports its own published-year coverage, so 'no spend', 'not published yet' and 'no join key' are three different answers instead of one null.\n\nMedicaid totals EXCLUDE the SDUD national roll-up, which CMS publishes under state 'XX' beside the 50 state rows and which would otherwise roughly double every Medicaid figure.\n\nReference demo: recall_number D-1489-2019 (Fresenius Kabi fluorouracil, Class I, window 2019-2022) exercises both legs and the NDC bridge. This description quotes NO dollar figure on purpose: the answer is the only place a number lives, so a change to the computation can never leave a stale figure in the documentation. It did once -- the demo totals here were the pre-2026-08-10 national-roll-up double count and stood six weeks after the fix.","layer":"L2","input_schema":{"type":"object","properties":{"recall_number":{"type":"string"},"detail_limit":{"type":"integer","default":25},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false,"required":["recall_number"]},"invariants":[],"underlying_silver_tables_for_pinning":["drug_silver.fact_drug_recall","drug_silver.fact_drug_spending_part_d","drug_silver.fact_drug_medicaid_utilization","drug_silver.dim_drug"],"semantic_views_used":[],"known_gaps":["medicaid_sdud_suppression_used_flag","part_d_puf_annual_grain_only"],"parameter_schema":{"type":"object","properties":{"recall_number":{"type":"string"},"detail_limit":{"type":"integer","default":25},"acknowledge_era_break":{"type":"boolean","default":false}},"additionalProperties":false,"required":["recall_number"]},"output_schema":{"$defs":{"AssertedAtSource":{"enum":["cms_index","http_last_modified","filename_inferred","unknown_default"],"title":"AssertedAtSource","type":"string"},"AttestationSignature":{"additionalProperties":false,"description":"Signed attestation hook. Phase 1: None. M-5.5 (queued) populates.\nHook structure locked here so M-5.5 lands without envelope schema changes.","properties":{"algorithm":{"const":"aws-kms-rsa-pss-sha256","title":"Algorithm","type":"string"},"key_arn":{"title":"Key Arn","type":"string"},"key_version":{"title":"Key Version","type":"string"},"signed_at":{"format":"date-time","title":"Signed At","type":"string"},"signature":{"title":"Signature","type":"string"},"signed_envelope_canonical":{"title":"Signed Envelope Canonical","type":"string"},"transparency_log_entry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transparency Log Entry"}},"required":["algorithm","key_arn","key_version","signed_at","signature","signed_envelope_canonical"],"title":"AttestationSignature","type":"object"},"Caveat":{"additionalProperties":false,"description":"Structured caveat. NOT free-form strings — typed so agents can branch\nprogrammatically. Sorted lexically by (caveat_type, severity) before hash\ncanonicalization (M-2 §2.4 sort rule).","properties":{"caveat_type":{"$ref":"#/$defs/CaveatType"},"severity":{"enum":["info","warning","error"],"title":"Severity","type":"string"},"message":{"title":"Message","type":"string"},"structured_fields":{"additionalProperties":true,"title":"Structured Fields","type":"object"}},"required":["caveat_type","severity","message"],"title":"Caveat","type":"object"},"CaveatType":{"description":"Phase 1 caveat catalog from M-5 §2.6. Expanded as features land.\n\nAdded 2026-05-14 per M-8 v2: `coverage_gap` (used by data_not_ingested\nprobe layer + historical CMS publication gaps in gap_registry.yaml)\nand `schema_drift` (cpsc_2008_bareform_columns,\ncpsc_2011_04_broomfield_duplicate_native_keys). Both were already\nreferenced from gap_registry.yaml as `str` caveat_types; promoting\nthem to first-class enum values closes the implicit-string gap.","enum":["not_yet_published","restatement_possible","cascade_stale","freshness_warning","era_boundary_warning","suppression_warning","parent_org_alias_applied","lineage_event_in_window","joinable_data_unavailable","methodology_blend_applied","precision_underflow","parse_revision_drift","coverage_delta_warning","cross_substrate_reconciliation","snapshot_consistency_violation","gap_explicitly_overridden","parent_alias_unresolved","undocumented_lineage_candidate","coverage_gap","schema_drift","methodology_note"],"title":"CaveatType","type":"string"},"Quality":{"additionalProperties":false,"description":"Quality flags surfaced from substrate-level invariants.","properties":{"is_outlier":{"default":false,"title":"Is Outlier","type":"boolean"},"confidence":{"default":1.0,"maximum":1.0,"minimum":0.0,"title":"Confidence","type":"number"},"precision_underflow":{"default":false,"title":"Precision Underflow","type":"boolean"},"has_reconciliation_warning":{"default":false,"title":"Has Reconciliation Warning","type":"boolean"},"reconciliation_warnings":{"items":{"type":"string"},"title":"Reconciliation Warnings","type":"array"},"is_aggregate_of_suppressed":{"default":false,"title":"Is Aggregate Of Suppressed","type":"boolean"},"has_cross_era_warning":{"default":false,"title":"Has Cross Era Warning","type":"boolean"},"real_world_freshness_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Age Days"},"real_world_freshness_half_life_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Real World Freshness Half Life Days"}},"title":"Quality","type":"object"},"ResultStatus":{"description":"Distinguishes architecture-failure from data-doesn't-exist.\nWithout this enum an empty result is ambiguous and the agent silently\ncomposes from adjacent tables (M-8 prevents this).\n\nEnum values are union of M-8 gating_type → result_status_mapping outputs\nplus three substrate-internal values (answered, answered_with_caveats,\narchitecture_gap). M-8 amendments may extend; M-5 amends in lockstep.\n\nAdded 2026-05-14 per M-8 v2 §0.1: `data_not_ingested` distinguishes\n\"we have not yet built this slice into silver\" (operational gap) from\n\"the data is structurally absent in CMS\" (data_not_published) or\n\"suppressed by CMS privacy rule\" (data_suppressed). Without this third\ncategory an agent receiving an empty silver result has no caveat to\nfire and silently composes from adjacent tables.","enum":["answered","answered_with_caveats","not_yet_published","data_gated","data_not_published","data_suppressed","data_not_ingested","out_of_scope","cross_era_blocked","architecture_gap"],"title":"ResultStatus","type":"string"},"SourceLineageEntry":{"additionalProperties":false,"description":"One contributing silver row-set for a derived response.","properties":{"table_fqn":{"title":"Table Fqn","type":"string"},"snapshot_id":{"title":"Snapshot Id","type":"integer"},"row_set_fingerprint":{"title":"Row Set Fingerprint","type":"string"}},"required":["table_fqn","snapshot_id","row_set_fingerprint"],"title":"SourceLineageEntry","type":"object"},"SourceMetadata":{"additionalProperties":false,"description":"Per-response source provenance. Bronze-anchored vs derived shape\nenforced by tool-author convention (CHECK at envelope build).","properties":{"source_id":{"title":"Source Id","type":"string"},"source_url":{"title":"Source Url","type":"string"},"s3_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"S3 Version Id"},"bronze_object_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bronze Object Key"},"sha256_content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sha256 Content Hash"},"source_lineage":{"anyOf":[{"items":{"$ref":"#/$defs/SourceLineageEntry"},"type":"array"},{"type":"null"}],"default":null,"title":"Source Lineage"},"parent_vintage_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Vintage Fingerprint"},"asserted_at_source":{"anyOf":[{"$ref":"#/$defs/AssertedAtSource"},{"type":"null"}],"default":null},"parser_version":{"title":"Parser Version","type":"string"},"fetcher_version":{"title":"Fetcher Version","type":"string"},"iceberg_table_fqns":{"items":{"type":"string"},"title":"Iceberg Table Fqns","type":"array"},"provenance_level":{"default":"not_evaluated","enum":["bronze_anchored","derived","not_evaluated"],"title":"Provenance Level","type":"string"}},"required":["source_id","source_url","parser_version","fetcher_version"],"title":"SourceMetadata","type":"object"}},"additionalProperties":false,"description":"Single-tool envelope. Every MCP tool returns one of these (or\nfails with an exception that the decorator translates).\n\nHash canonicalization rules: M-2 §2.4. Fields included in canonical\nform: all of value, unit, methodology, methodology_era, snapshot_set,\nvintage, cms_vintage_sequence, parse_revision, source.*,\nparser_artifact_hash, invariants_applied, caveats, quality.*.\nExcluded: audit_id, timestamp, request_id, data_as_of, response_hash,\ntenant_id (request-scoped or chicken-and-egg).","properties":{"value":{"title":"Value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"result_status":{"$ref":"#/$defs/ResultStatus"},"methodology":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Methodology"},"methodology_era":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Era"},"methodology_blend_factors":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Methodology Blend Factors"},"source":{"$ref":"#/$defs/SourceMetadata"},"snapshot_set":{"additionalProperties":{"type":"integer"},"description":"{table_fqn → iceberg_snapshot_id (int64)}. Per M-2 §2.2.","title":"Snapshot Set","type":"object"},"vintage":{"default":"as_restated","enum":["as_published","as_restated"],"title":"Vintage","type":"string"},"vintage_basis":{"default":"default_unmeasured","enum":["query_plan","caller","default_unmeasured"],"title":"Vintage Basis","type":"string"},"cms_vintage_sequence":{"minimum":1,"title":"Cms Vintage Sequence","type":"integer"},"parse_revision":{"default":1,"minimum":1,"title":"Parse Revision","type":"integer"},"as_of_observed":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Observed"},"as_of_asserted":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Asserted"},"as_of_effective":{"anyOf":[{"format":"date","type":"string"},{"type":"null"}],"default":null,"title":"As Of Effective"},"quality":{"$ref":"#/$defs/Quality"},"invariants_applied":{"items":{"type":"string"},"title":"Invariants Applied","type":"array"},"caveats":{"items":{"$ref":"#/$defs/Caveat"},"title":"Caveats","type":"array"},"confidence":{"anyOf":[{"maximum":1.0,"minimum":0.0,"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"confidence_basis":{"anyOf":[{"enum":["tool_measured","not_evaluated"],"type":"string"},{"type":"null"}],"default":null,"title":"Confidence Basis"},"finality_confidence":{"anyOf":[{"enum":["low","medium","high","empirical_final"],"type":"string"},{"type":"null"}],"default":null,"title":"Finality Confidence"},"response_hash":{"description":"SHA-256 of canonicalized form per M-2 §2.4.","title":"Response Hash","type":"string"},"semantic_version":{"minimum":1,"title":"Semantic Version","type":"integer"},"tool_version":{"title":"Tool Version","type":"string"},"parser_artifact_hash":{"title":"Parser Artifact Hash","type":"string"},"parser_artifact_hash_basis":{"default":"not_evaluated","enum":["supplied","tool_source_sha256","not_evaluated"],"title":"Parser Artifact Hash Basis","type":"string"},"signature":{"anyOf":[{"$ref":"#/$defs/AttestationSignature"},{"type":"null"}],"default":null},"tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Calling tenant slug, resolved by the binding and stamped via the per-call tenant context. Defaults to the bootstrap 'internal' tenant for local/in-process callers.","title":"Tenant Id"},"status":{"default":"complete","enum":["complete","partial","refused","failed","queued"],"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","enum":["fresh","due","late","stale","frozen","unknown"],"title":"Freshness State","type":"string"},"audit_id":{"description":"UUID; ties to medicare_silver.audit_log row.","title":"Audit Id","type":"string"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"},"request_id":{"title":"Request Id","type":"string"},"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Data As Of"}},"required":["value","result_status","source","snapshot_set","cms_vintage_sequence","response_hash","semantic_version","tool_version","parser_artifact_hash","audit_id","timestamp","request_id"],"title":"BaseResponse","type":"object"},"_m7_substrate":true,"title":"Recall Spend Window","annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}]}