find_data_sources

What it answers

1. 1Search the Vlada substrate catalog by keyword.
2. 2Returns the matching data sources (commercial TiC, hospital HPT, Medicare, drug pricing, provider identity, curated marts, provenance registries) ranked by relevance.
3. 3Compact by default (identity + queryable + claim ceiling + the exact describe_data_source call per hit); pass verbosity='full' for the previous full source_product_card per result.
4. 4Paginates with limit (default 25, max 200) + offset; the response carries total_count, returned_count, and offset.
5. 5Optional filters: {domain, stage, status, limit}.
6. 6Agents call this first to discover what data Vlada has.
7. 7Since 2026-09-02 the answer leads with DATA POINTS (`data_points`: the measure/dimension asked for, with its source, door, table.column and must-read trap) and the table cards follow as physical locations.
8. 8Every hit carries `source_code` -- the one public code, which describe_data_source accepts verbatim -- alongside the table's `source_fqn`.
9. 9Points and tables are ranked by ONE ranker (the authored data-point scorer).
10. 10Retired tables are never returned; they appear only as `supersedes` on the live successor's card.
11. 11BOUNDED (2026-09-18): the default call is compact and paged -- both the table cards and the data points come back a page at a time, each with its own total and next offset -- so a default call can never truncate.
12. 12Pass verbosity='full' for the whole point record and the full source_product_card per hit.

Inputs (7)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
find_data_sources(query="medicare physician fee schedule", limit=5)

curl -X POST https://api.vladahealth.com/v1/tools/find_data_sources \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"medicare physician fee schedule","limit":5}'

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

A real answer

{
 "value": {
  "query": "medicare physician fee schedule",
  "filters": null,
  "verbosity": "compact",
  "status": "matched",
  "retrieval_mode": "lexical",
  "scope_verification": {
   "status": "not_verified",
   "basis": "catalog_match_only",
   "geography": "not_verified",
   "time_coverage": "not_verified",
   "population": "not_verified",
   "completeness": "not_verified"
  },
  "ranker": "authored_data_point_scorer",
  "excludes": "retired",
  "data_points": [
   {
    "rank": 1,
    "world": "w2",
    "data_point": {
     "id": "w2.puf.physician_avg_medicare_allowed",
     "name": "Medicare average allowed amount by provider and service",
     "unit": "USD_per_service",
     "kind": "measure"
    },
    "source": {
     "id": "cms_puf_physician_other_practitioners",
     "source_code": "cms_puf_physician_other_practitioners",
     "title": "Medicare Physician & Other Practitioners public use files (by provider and service; by geography and service)",
     "how_to_reach_it": "sql"
    },
    "location": {
     "table": "medicare_silver.fact_physician_by_provider_service",
     "column": "avg_medicare_allowed",
     "variants": [
      "paid=avg_medicare_payment",
      "standardized=avg_medicare_standardized",
      "submitted=avg_submitted_charge",
      "services=tot_services",
      "beneficiaries=tot_benes"
     ],
     "required_filters": [
      "is_current=true"
     ]
    },
    "trap": {
     "must_read": "Always filter data_year and a state or code; averages of paid claims; null is suppressed.",
     "ids": [
      "data_year_pin",
      "claims_average_not_fee_schedule",
      "small_cell_suppressed_null",
      "heavy_scan"
     ]
    },
    "next": "bounded query_substrate on medicare_silver.fact_physician_by_provider_service",
    "fetch": "describe_data_source(source_fqn='cms_puf_physician_other_practitioners')",
    "relevance": 51
   },
   {
    "rank": 2,
    "world": "w2",
    "data_point": {
     "id": "w2.pfs.national_allowed_amount",
     "name": "PFS national allowed amount",
     "unit": "USD",
     "kind": "rate"
    },
    "source": {
     "id": "cms_pfs_relative_value_files",
     "source_code": "cms_pfs_relative_value_files",
     "title": "Physician Fee Schedule relative value files (RVUs, indicators, conversion factor, GPCI, locality configuration)",
     "how_to_reach_it": "sql"
    },
    "location": {
     "table": "medicare_silver.fact_pfs_rvu",
     "column": "conversion_factor",
     "variants": [
      "total_nonfacility_rvu=total_non_facility_rvu",
      "total_facility_rvu=total_facility_rvu",
      "status=status_code"
     ],
     "required_filters": []
    },
    "trap": {
     "must_read": "Compute RVU x conversion factor after filtering implausible rows; status_code says whether the code is payable; national only.",
     "ids": [
      "year_pin",
      "implausible_conversion_factor_rows",
      "locality_not_on_rvu"
     ]
    },
    "next": "call medicare_allowed",
    "fetch": "describe_data_source(source_fqn='cms_pfs_relative_value_files')",
    "relevance": 45
   },
   {
    "rank": 3,
    "world": "w2",
    "data_point": {
     "id": "w2.clfs.national_limit_amount",
     "name": "CLFS national limitation amount",
     "unit": "USD",
     "kind": "rate"
    },
    "source": {
     "id": "cms_clfs_national_rates",
     "source_code": "cms_clfs_national_rates",
     "title": "Clinical Laboratory Fee Schedule (national limitation amounts)",
     "how_to_reach_it": "sql"
    },
    "location": {
     "table": "medicare_silver.fact_clfs_national_rate",
     "column": "national_limit_amount",
     "variants": [],
     "required_filters": []
    },
    "trap": {
     "must_read": "Pin calendar_year and quarter; do not union with the legacy locality table.",
     "ids": [
      "quarter_pin"
     ]
    },
    "next": "bounded query_substrate on medicare_silver.fact_clfs_national_rate",
    "fetch": "describe_data_source(source_fqn='cms_clfs_national_rates')",
    "relevance": 42
   }
  ],
  "data_points_total_count": 3,
  "data_points_returned_count": 3,
  "data_points_detail_hint": "verbosity='full' returns grain, time pin, nulls, variants and basis for each point; describe_data_source(source_code) returns the table to query and a verified example.",
  "match_count": 322,
  "returned": 5,
  "total_count": 322,
  "returned_count": 5,
  "offset": 0,
  "limit": 5,
  "results": [
   {
    "source_id": "cms_physician_by_provider_service",
    "source_code": "cms_puf_physician_other_practitioners",
    "title": "Medicare Physician & Other Practitioners \u2014 by Provider and Service (granular price)",
    "published_source_code": "cms_puf_physician_other_practitioners",
    "how_to_reach_it": "sql",
    "domain": "medicare",
    "status": "live",
    "grain": "One row per (data_year, rendering NPI, HCPCS, place of service) \u2014 charge/allowed/paid.",
    "queryable": true,
    "not_queryable_reason": null,
    "claim_ceiling": "queryable",
    "fetch": "describe_data_source(source_fqn='medicare_silver.fact_physician_by_provider_service')",
    "fetch_unavailable_reason": null,
    "relevance": 1051,
    "relevance_basis": "data_point",
    "relevance_why": "holds data point w2.puf.physician_avg_medicare_allowed",
    "world": "Medicare",
    "view": "By doctor"
   },
   {
    "source_id": "medicare_physician_payment_by_geo",
    "source_code": "cms_puf_physician_other_practitioners",
    "title": "Medicare Physician & Other Practitioners by Geography (avg allowed/payment per HCPCS)",
    "published_source_code": "cms_puf_physician_other_practitioners",
    "how_to_reach_it": "sql",
    "domain": "medicare",
    "status": "live",
    "grain": "One row per (geography [National|State], HCPCS, place-of-service) per data year.",
    "queryable": true,
    "not_queryable_reason": null,
    "claim_ceiling": "queryable",
    "fetch": "describe_data_source(source_fqn='medicare_silver.fact_physician_payment_by_geo')",
    "fetch_unavailable_reason": 
…

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)