query

What it answers

1. 1SAFE STUB.
2. 2Given 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).
3. 3Never executes SQL.
4. 4A source outside the queryable set (retired / partial / planned / unattributed) gets no executable path and the rule that excluded it.
5. 5COLUMNS (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.
6. 6IDENTIFIERS (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.

Inputs (2)

Call it

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

curl -X POST https://api.vladahealth.com/v1/tools/query \
  -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/query/schema

A real answer

{
 "value": {
  "source_code": "cms_pfs_relative_value_files",
  "resolved_via": "register_source_code",
  "accepted": true,
  "executed": false,
  "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"
   ]
  },
  "status": "live",
  "superseded_by": null,
  "queryable": true,
  "not_queryable_reason": null,
  "requested_params": null,
  "how_to_query": {
   "executable_paths": [
    {
     "lane": "sync",
     "tool": "query_substrate",
     "when": "small, bounded reads (LIMIT-capped, ~few hundred wide rows per page)",
     "call": {
      "tool": "query_substrate",
      "arguments": {
       "max_rows": 25
      }
     }
    },
    {
     "lane": "async",
     "tools": [
      "submit_query",
      "poll_query",
      "fetch_query"
     ],
     "when": "a scan that needs more time than the request path allows",
     "call": {
      "tool": "submit_query",
      "arguments": {
       "tool": "query_substrate",
       "arguments": {
        "max_rows": 25
       }
      }
     },
     "then": "poll_query(job_id) until done, then fetch_query(job_id)"
    }
   ],
   "rules": [
    "read-only SELECT with an explicit LIMIT (capped at 10,000; the delivered payload is bounded and truncation is reported)",
    "apply the source card's known_gaps yourself -- raw SQL enforces safety, not methodology"
   ]
  },
  "catalog_declared_surface": {
   "note": "catalog prose describing where the data lives; NOT an executable path from this MCP. Use how_to_query."
  },
  "note": "query() is a discovery stub -- it does not execute SQL. Every path in how_to_query is callable from this MCP; nothing else is implied."
 },
 "unit": null,
 "vintage": null,
 "source": {
  "dataset": "Physician Fee Schedule relative value files (RVUs, indicators, conversion factor, GPCI, locality configuration)",
  "publisher": "cms",
  "catalog_updated_at": "2026-06-03"
 },
 "methodology": null,
 "caveats": [],
 "response_hash": "d7b72644e1caafd841693284ad4629696e3c9f5789107f0d0fe260ab7fa3311c",
 "semantic_version": 1,
 "tool_version": "query@0.3.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "scope": {
   "tool": "query",
   "filters": {
    "source_fqn": "cms_pfs_relative_value_files"
   }
  }
 },
 "method": "Your SQL ran as one read-only query over 0 tables, named in this answer's evidence. The calculation is the one your SQL expresses; nothing was aggregated or adjusted on top of it.",
 "evidence": {
  "sources": [
   {
    "dataset": "Physician Fee Schedule relative value files (RVUs, indicators, conversion factor, GPCI, locality configuration)",
    "publisher": "cms",
    "catalog_updated_at": "2026-06-03"
   }
  ],
  "response_hash": "d7b72644e1caafd841693284ad4629696e3c9f5789107f0d0fe260ab7fa3311c"
 },
 "as_of": "2026-11-09",
 "as_of_basis": "the catalog of data sources this answer was composed from"
}

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)