describe_entity

What it answers

1. 1Everything layer one holds about one entity (an entity_id from resolve_entity): what it is and its identifiers; who owned or controlled it on a date (on=YYYY-MM-DD, default today), the path to the top parent with each hop's basis, grade, dates and evidence; what it holds (contracts, plans, Medicaid plans, issuers, subsidiaries), or everything under its top parent with scope=group; its dated corporate events (acquisitions, mergers, transfers of business, renames) with filings.
2. 2Every date follows the doctrine (at least since; last seen).

Inputs (5)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
describe_entity(entity_id="le:000160", on="2026-10-01")

curl -X POST https://api.vladahealth.com/v1/tools/describe_entity \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_id":"le:000160","on":"2026-10-01"}'

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

A real answer

{
 "value": {
  "found": true,
  "not_found_reason": null,
  "query": {
   "entity_id": "le:000160",
   "on": "2026-10-01",
   "scope": "entity",
   "events": true
  },
  "status": "found",
  "entity": {
   "entity_id": "le:000160",
   "kind": "legal_entity",
   "label": "UnitedHealthcare Benefits of Texas, Inc.",
   "status": "active",
   "build": "v3o"
  },
  "identifiers": [
   {
    "namespace": "cms_org_name",
    "value": "UNITEDHEALTHCARE BENEFITS OF TEXAS, INC.",
    "valid_from": "2011-07-01",
    "valid_to": "2023-12-31",
    "evidence_id": "ev:ma_name:le:000160"
   },
   {
    "namespace": "cms_org_name",
    "value": "UnitedHealthcare Benefits of Texas, Inc.",
    "valid_from": "2022-01-01",
    "valid_to": "",
    "evidence_id": "ev:ma_name:le:000160"
   },
   {
    "namespace": "ein",
    "value": "330115163",
    "valid_from": "2013-01-01",
    "valid_to": "",
    "evidence_id": "ev:mlr_id:le:000160:ein"
   },
   {
    "namespace": "naic",
    "value": "95174",
    "valid_from": "2013-01-01",
    "valid_to": "",
    "evidence_id": "ev:mlr_id:le:000160:naic"
   }
  ],
  "owners": {
   "top": "le:000013",
   "path": [
    {
     "from": "le:000160",
     "to": "le:000013",
     "rel": "controlled_by",
     "basis": "reported_ultimate_parent",
     "grade": "B",
     "dates": {
      "from": "2011-07-01",
      "from_is": "at least since",
      "to": null,
      "to_is": "still true"
     },
     "event_id": null,
     "evidence_id": "ev:ma_parent:le:000160:le:000013:2011-07",
     "settled_by_document": false,
     "to_label": "UnitedHealth Group, Inc."
    }
   ],
   "on": "2026-10-01",
   "top_label": "UnitedHealth Group, Inc."
  },
  "holdings": {
   "scope": "entity",
   "roots": [
    "le:000160"
   ],
   "counts": {
    "contracts": 5,
    "plans": 0,
    "medicaid_plans": 0,
    "issuers": 1,
    "subsidiaries": 0,
    "groups": 0,
    "brands": 0,
    "other": 0
   },
   "contracts": [
    {
     "entity_id": "contract:H0609",
     "label": "H0609",
     "holder": "le:000160",
     "rel": "held_by",
     "basis": "",
     "grade": "A",
     "dates": {
      "from": "2022-01-01",
      "from_is": "start",
      "to": null,
      "to_is": "still true"
     }
    },
    {
     "entity_id": "contract:H0624",
     "label": "H0624",
     "holder": "le:000160",
     "rel": "held_by",
     "basis": "",
     "grade": "A",
     "dates": {
      "from": "2022-01-01",
      "from_is": "start",
      "to": null,
      "to_is": "still true"
     }
    },
    {
     "entity_id": "contract:H1360",
     "label": "H1360",
     "holder": "le:000160",
     "rel": "held_by",
     "basis": "",
     "grade": "A",
     "dates": {
      "from": "2022-01-01",
      "from_is": "start",
      "to": null,
      "to_is": "still true"
     }
    },
    {
     "entity_id": "contract:H3805",
     "label": "H3805",
     "holder": "le:000160",
     "rel": "held_by",
     "basis": "",
     "grade": "A",
     "dates": {
      "from": "2022-01-01",
      "from_is": "start",
      "to": null,
      "to_is": "still true"
     }
    },
    {
     "entity_id": "contract:H6706",
     "label": "H6706",
     "holder": "le:000160",
     "rel": "held_by",
     "basis": "",
     "grade": "A",
     "dates": {
      "from": "2022-01-01",
      "from_is": "start",
      "to": null,
      "to_is": "still true"
     }
    }
   ],
   "plans": [],
   "medicaid_plans": [],
   "issuers": [
    {
     "entity_id": "hios:70754",
     "label": "UnitedHealthcare Benefits of Texas, Inc.",
     "holder": "le:000160",
     "rel": "held_by",
     "basis": "",
     "grade": "A",
     "dates": {
      "from": "2013-01-01",
      "from_is": "start",
      "to": null,
      "to_is": "still true"
     }
    }
   ],
   "subsidiaries": [],
   "groups": [],
   "brands": [],
   "other": [],
   "truncated": false
  },
  "events": [],
  "evidence": {
   "ev:ma_parent:le:000160:le:000013:2011-07": {
    "evidence_id": "ev:ma_parent:le:000160:le:000013:2011-07",
    "source_type": "official_register",
    "field": "parent_org_raw"
   }
  }
 },
 "unit": "ontology_entity",
 "vintage": "2026-10-28",
 "source": {
  "dataset": "Vlada ontology layer one (who holds and who owns every payer instrument, over time)",
  "publisher": "vlada",
  "catalog_updated_at": "2026-10-28"
 },
 "caveats": [],
 "response_hash": "0042c6cdafe5db00c3988f2af2a7750224d1306895ecdbb432c1f72cef0aa4b4",
 "semantic_version": 1,
 "tool_version": "describe_entity@2.0.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "ontology_entity",
  "scope": {
   "tool": "describe_entity",
   "filters": {
    "entity_id": "le:000160",
    "scope": "entity",
    "events": true,
    "limit": 200
   }
  }
 },
 "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 events; yes was used. You did not specify limit; 200 was used. You did not specify scope; entity was used.",
 "evidence": {
  "sources": [
   {
    "dataset": "Vlada ontology layer one (who holds and who owns every payer instrument, over time)",
    "publisher": "vlada",
    "catalog_updated_at": "2026-10-28"
   }
  ],
  "response_hash": "0042c6cdafe5db00c3988f2af2a7750224d1306895ecdbb432c1f72cef0aa4b4"
 },
 "defaults_applied": [
  {
   "param": "events",
   "used": true,
   "reason": "tool default"
  },
  {
   "param": "limit",
   "used": 200,
   "reason": "tool default"
  },
  {
   "param": "scope",
   "used": "entity",
   "reason": "tool default"
  }
 ]
}

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": "DescribeEntityResponse",
 "type": "object"
}

Sources

Known limits (4)

1. 1Layer one only: no facilities, doctors, networks or PBMs (layers two to five follow on Ben's signature).
2. 2About 16% of Medicare Advantage members sit under a chain with one hop resting on CMS's parent string alone (grade B); the top parent is not in doubt, the corroborating filing is not yet attached.
3. 3Belief time (what an earlier build served) is not yet queryable; every answer carries the build it was read from.
4. 4The 233 open review-queue rows (candidate contract transfers) are not served.