describe_schema

What it answers

1. 1Return the semantic layer: marts, columns, invariants, canonical payers, and the tools YOU can call (the same list tools/list returns for you, never a wider catalog).
2. 2Compact by default (a manifest: marts + a name + one-line summary per tool, under ~8K chars).
3. 3Fetch one section with describe_schema(section='<mart>') / section='tools' / section='invariants'.
4. 4Pass verbosity='full' for the previous full payload.
5. 5Agents call this first to learn the surface, then fetch the section or tool they need.

Inputs (7)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
describe_schema(limit=10)

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

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

A real answer

{
 "value": {
  "version": 1,
  "verbosity": "compact",
  "note": "Compact manifest. Fetch one section with describe_schema(section='<mart>'), or pass verbosity='full' for the previous full payload.",
  "mart_count": 4,
  "marts": [
   {
    "name": "fact_rate",
    "status": "partial",
    "superseded_by": null,
    "columns": 17,
    "approx_bytes": 3887,
    "fetch": "describe_schema(section='fact_rate')"
   },
   {
    "name": "mart_rate_by_code",
    "status": "retired",
    "retired": true,
    "columns": 17,
    "approx_bytes": 3894,
    "fetch": "describe_schema(section='mart_rate_by_code')"
   },
   {
    "name": "mart_rate_by_entity",
    "status": "live",
    "superseded_by": null,
    "columns": 17,
    "approx_bytes": 4004,
    "fetch": "describe_schema(section='mart_rate_by_entity')"
   },
   {
    "name": "rate_provider_edge",
    "status": "live",
    "superseded_by": null,
    "columns": 12,
    "approx_bytes": 3016,
    "fetch": "describe_schema(section='rate_provider_edge')"
   }
  ],
  "tool_count": 58,
  "tools": [
   {
    "name": "asp_pricing_lookup",
    "summary": "Given an HCPCS code or short-description search, returns Medicare Part B ASP quarterly payment-li..."
   },
   {
    "name": "certified_measure",
    "summary": "Run a GOVERNED KPI by name from the certified measures registry."
   },
   {
    "name": "compare_hospital_rates",
    "summary": "NEGOTIATED RATES BY INSURER AND PLAN ARE SERVED HERE: hospital price-transparency files carry the..."
   },
   {
    "name": "describe_data_source",
    "summary": "Return the catalog record for one substrate data source."
   },
   {
    "name": "describe_entity",
    "summary": "Everything layer one holds about one entity (an entity_id from resolve_entity): what it is and it..."
   },
   {
    "name": "describe_schema",
    "summary": "Return the semantic layer: marts, columns, invariants, canonical payers, and the tools YOU can ca..."
   },
   {
    "name": "excluded_prescriber_payment_screen",
    "summary": "Given an NPI (10-digit), returns OIG LEIE exclusion status and \u2014 if excluded \u2014 any Open Payments..."
   },
   {
    "name": "fetch_query",
    "summary": "Fetch the result of an async job once it is done."
   },
   {
    "name": "find_data_sources",
    "summary": "Search the Vlada substrate catalog by keyword."
   },
   {
    "name": "find_views",
    "summary": "Look up the vetted analytic VIEWS for a question before you query."
   }
  ],
  "invariants": {
   "count": 5,
   "ids": [
    "methodology_conflict",
    "outlier_bounds",
    "uhc_custom_code_expansion",
    "placeholder_allowed_amount"
   ]
  },
  "payers": {
   "count": 45,
   "sample": [
    "uhc",
    "anthem",
    "aetna",
    "cigna",
    "humana",
    "kaiser",
    "centene",
    "premera",
    "geisinger",
    "health_partners"
   ]
  },
  "codes": {
   "systems": [
    "CPT",
    "HCPCS",
    "MS-DRG",
    "CDT",
    "ICD",
    "CUSTOM"
   ],
   "common_count": 6
  },
  "sections": {
   "mart": "describe_schema(section='<mart_name>') for one mart's columns",
   "tools": "describe_schema(section='tools') for tool descriptions + params (paginated)",
   "invariants": "describe_schema(section='invariants') for full invariant text",
   "full": "describe_schema(verbosity='full') for the entire payload"
  }
 },
 "unit": null,
 "vintage": null,
 "methodology": null,
 "caveats": [],
 "response_hash": "bdd61486fd9a21be3b43d47ca4a9c6442fd915459ee8cfa72be6feed0e079dd9",
 "semantic_version": 1,
 "tool_version": "describe_schema@1.0.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "scope": {
   "tool": "describe_schema",
   "filters": {
    "verbosity": "compact",
    "limit": 10,
    "offset": 0,
    "include_invariants": true,
    "include_examples": true
   }
  }
 },
 "method": "Computed over the filters shown in this answer's scope, from the sources listed in its evidence. Nothing outside those filters was included. You did not specify include_examples; yes was used. You did not specify include_invariants; yes was used. You did not specify offset; 0 was used. You did not specify verbosity; compact was used.",
 "evidence": {
  "response_hash": "bdd61486fd9a21be3b43d47ca4a9c6442fd915459ee8cfa72be6feed0e079dd9"
 },
 "defaults_applied": [
  {
   "param": "include_examples",
   "used": true,
   "reason": "tool default"
  },
  {
   "param": "include_invariants",
   "used": true,
   "reason": "tool default"
  },
  {
   "param": "offset",
   "used": 0,
   "reason": "tool default"
  },
  {
   "param": "verbosity",
   "used": "compact",
   "reason": "tool default"
  }
 ],
 "paging": {
  "section": "value.tools",
  "returned": 10,
  "total": 58,
  "next_offset": 10,
  "recover_with": [
   {
    "tool": "describe_schema",
    "arguments_hint": {
     "offset": 10,
     "limit": 10
    },
    "note": "10 of 58 value.tools entries are in this answer. Re-ask with offset=10 for the next page, or narrow the question so the whole answer fits."
   }
  ],
  "applied": "limit=10"
 },
 "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": "SchemaResponse",
 "type": "object"
}

Sources

Known limits (0)