Home / Tools / Curated datasets
describe_data_source
Describe Data Source
What it answers
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, so find -> describe never fails on the identifier space. 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_fqnverbosityCall it
From an agent: connect the Vlada MCP once (one click for Claude, ChatGPT, Cursor, VS Code) and ask in plain English; the agent selects describe_data_source when the question fits. From code: the same tool over REST with an API key. The schema endpoint needs no key.
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":"<source_fqn>"}'curl https://api.vladahealth.com/v1/tools/describe_data_source/schema # the JSON schema, no auth # MCP endpoint (Streamable HTTP): https://mcp.vladahealth.com/mcp
What comes back
Typed rows plus provenance on every answer: the public source file, its vintage, the methodology, and a response_hash you can replay. Prove and replay tools turn any number into a re-runnable receipt. A number the data cannot support comes back as “not in the data”, never as zero.
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,
"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 behind it
Known limits
No gaps recorded for this tool. Absence of a recorded gap is not a claim of complete coverage; the answer itself says what it covers.
As of the 2026-09-19 build of the served surface · machine-readable catalog · the live server may run a different version; the schema endpoint above is authoritative for what is deployed.