describe_data_source

What it answers

1. 1Return the catalog record for one substrate data source.
2. 2Compact 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.
3. 3IDENTIFIERS: 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.
4. 4Also accepts a data-point ID, returning its exact bound table plus the selected point's units, grain, nulls and execution route.
5. 5When the card includes a coverage-check recipe, run its stated query to inspect retained editions; it is not measured coverage.
6. 6Do not infer all-history coverage from current-only rows.
7. 7Avoid extra schema calls when this card already supplies the needed columns.
8. 8A RETIRED source answers with a redirect (status retired + superseded_by + the successor's fqn), never a card.
9. 9COLUMNS (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.
10. 10A 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.
11. 11WHAT TO QUERY (2026-09-18): every card carries a block saying what to type.
12. 12It 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.
13. 13A 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.
14. 14Column lists are split: the data columns first, the row-lineage columns every row carries in their own named group.

Inputs (2)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
describe_data_source(source_fqn="cms_pfs_relative_value_files")

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

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

A real answer

{
 "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 = <the year or period you mean>",
     "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
…

What comes back

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "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"
}

Sources

Known limits (0)