# describe_data_source Describe Data Source · v1.3.0 · curated 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. **Inputs.** - `source_fqn` (required): - `verbosity`: **A real answer** (customer seat, 0.09 s, args `{"source_fqn":"cms_pfs_relative_value_files"}`): ```json { "value": { "source_code": "cms_pfs_relative_value_files", "resolved_via": "register_source_code", "found": true, "query_with": { "how_to_reach_it": "sql", "source_code": "cms_pfs_relative_value_files", "table": "medicare_silver.fact_pfs_rvu", "table_is_what_to_type": "query_substrate reads TABLES. The name it accepts for this source is medicare_silver.fact_pfs_rvu. 'cms_pfs_relative_value_files' is the catalog's name for the publisher release and is not a table.", "tool": "query_substrate", "required_predicates": [ { "clause": "WHERE is_current", "why": "this table keeps every vintage it has ever been given; without this predicate you are reading version history, not the current version", "enforced_by": "query_substrate defaults simple reads to current rows. For intentional history, explicitly select or filter is_current; the guard permits that without adding a current-only filter. Current-only results do not establish all retained editions.", "column": "is_current" }, { "clause": "WHERE calendar_year = ", "why": "every value on this table is for one calendar_year; without a pin you are mixing editions", "enforced_by": "you (the door does not apply methodology)", "column": "calendar_year" } ], "example": { "tool": "query_substrate", "arguments": { "sql": "SELECT calendar_year, hcpcs_code, modifier, status_code, code_description, work_rvu FROM medicare_silver.fact_pfs_rvu WHERE is_current LIMIT 5", "max_rows": 5 } }, "example_is": "a shape probe: 5 rows so you can see the table. Add every predicate above before you read a number out of it.", "example_validated": { "accepted": true, "checked_against": "vlada.query.sql_guard.validate_read_only_select (the same guard query_substrate runs)", "sql_as_the_door_runs_it": "SELECT calendar_year, hcpcs_code, modifier, status_code, code_description, work_rvu FROM medicare_silver.fact_pfs_rvu WHERE is_current LIMIT 5" }, "entitled": true, "other_tables_in_this_source": [ "medicare_silver.fact_pfs_gpci_locality", "medicare_silver.fact_pfs_locality_config", "medicare_silver.medicare_conversion_factor", "medicare_silver.medicare_pfs_indicators" ] }, "verbosity": "compact", "published_source": { "source_id": "cms_pfs_relative_value_files", "title": "Physician Fee Schedule relative value files (RVUs, indicators, conversion factor, GPCI, locality configuration)", "world": "w2", "publisher": "cms", "landing_page": "https://www.cms.gov/medicare/payment/fee-schedules/physician/pfs-relative-value-files", "how_to_reach_it": "sql", "baked_steer": null, "traps": [ { "id": "year_pin", "rule": "Every value is for one calendar year; pin calendar_year." }, { "id": "implausible_conversion_factor_rows", "rule": "1,432 CY2022-2025 rows carry implausible conversion_factor values; filter conversion_factor BETWEEN 20 AND 50." }, { "id": "locality_not_on_rvu", "rule": "RVU rows are national; a locality-adjusted amount needs GPCI joined on (calendar_year, state, locality_number)." } ], "edition_axes": [ "calendar_year" ], "holdings": [ { "start": "2003", "end": "2026", "grain": "year" } ], "newest_held": { "edition": "2026", "measured_at": "2026-10-12" }, "verification": "verified", "data_points": [ "w2.pfs.work_rvu", "w2.pfs.national_allowed_amount" ] }, "how_to_query_well": { "pin_the_period": { "required": true, "why": "an unpinned period silently mixes editions; the catalog marks this table pin=required", "vintage_columns": [ "calendar_year" ], "clause_in": "query_with.required_predicates" }, "grain_keys": [ "calendar_year", "hcpcs_code", "modifier", "vintage_tag" ] }, "summary": { "catalog_source_id": "medicare_pfs", "source_id": "medicare_pfs", "title": "Medicare Physician Fee Schedule (PFS)", "domain": "medicare", "status": "live", "superseded_by": null, "grain": "One row per (hcpcs_code, modifier, calendar_year) -- CMS PFS RVU components (work/PE/MP RVUs + conversion_factor). DEEP CY2003-2026. Filter conversion_factor BETWEEN 20 AND 50. RBP prices at the cl...", "row_count": 642307, "queryable": true, "not_queryable_reason": null, "claim_ceiling": "queryable", "freshness_sla": "Annual (CMS publishes ~early November, effective Jan 1); mirror refreshed from RDS.", "top_caveats": [ "National payment only \u2014 no locality column; join GPCI/locality tables for a locality-adjusted rate." ], "columns": [ { "name": "calendar_year", "type": "int" }, { "name": "hcpcs_code", "type": "string" }, { "name": "modifier", "type": "string" }, { "name": "status_code", "type": "string" }, { "name": "code_description", "type": "string" }, { "name": "work_rvu", "type": "decimal(38,12)" }, { "name": "non_facility_pe_rvu", "type": "decimal(38,12)" }, { "name": "facility_pe_rvu", "type": "decimal(38,12)" }, { "name": "mp_rvu", "type": "decimal(38,12)" }, { "name": "total_non_facility_rvu", "type": "decimal(38,12)" }, { "name": "total_facility_rvu", "type": "decimal(38,12)" }, { "name": "conversion_factor", "type": "decimal(38,12)" }, { "name": "global_period", "type": "string" }, { "name": "pre_service_time", "type": "decimal(38,12)" }, { "name": "intra_service_time", "type": "decimal(38,12)" }, { "name": "post_service_time", "type": "decimal(38,12)" }, { "name": "mult_proc_indicator", "type": "string" }, { "name": "bilateral_surge ... (truncated) ``` REST: `POST https://api.vladahealth.com/v1/tools/describe_data_source` with the inputs as the JSON body. MCP: the tool by name.