# query Query · v0.3.0 · curated 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. **Inputs.** - `source_fqn` (required): - `sql_or_params`: **A real answer** (customer seat, 0.62 s, args `{"source_fqn":"cms_pfs_relative_value_files"}`): ```json { "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 = ", "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" } ``` REST: `POST https://api.vladahealth.com/v1/tools/query` with the inputs as the JSON body. MCP: the tool by name.