describe_entity

The entity’s bound table, identity column, and full column list — one round-trip.

Layer: Semantic layer

The entity’s bound table, identity column, description, and full column list. One round-trip gives the agent everything it needs to compose SQL against the entity.

{
  "name": "customer",
  "description": "A registered user who can place orders.",
  "qualified_table": "public.users",
  "identity": "id",
  "origin": "manual",
  "columns": [
    {"name": "id", "data_type": "bigint", "nullable": false, "description": "...", "pii_sensitivity": "public"},
    {"name": "email", "data_type": "text", "nullable": false, "description": "...", "pii_sensitivity": "public"}
  ],
  "token_estimate": 184
}

pii_sensitivity reflects the per-column tag set at index time by the PII classifier — one of public, internal, confidential, or pii. The parallel pii_categories list (e.g. ["contact"]) gives the underlying category names that drove that sensitivity. Block-on-sensitivity routing flows through get_metric, which propagates pii_categories from the classifier; this field exposes the same signal for read-time UX choices.

Pass name as a bare identifier — customer, not public.customer. The schema qualifier belongs on the bound table, not the entity name. Errors surface as unknown_name with a list_entities recovery hint.