DescribeTable: full metadata for a SQL Server table

DescribeTable returns a comprehensive metadata snapshot of a single table in one round-trip: table identity, every column with its data type and extended-property description, non-primary-key indexes, key constraints (primary key and unique constraints), foreign keys including both the source and referenced column lists, and table-level triggers with their enabled state and event types. When the AI Insights layer is active it also attaches cached insight data that agents can use to avoid redundant schema investigations. Prefer DescribeTable over writing ad-hoc sys.* queries for a single table — it coalesces six catalog queries into one structured response.

Parameter

name

string

required

The table to describe. Accepts either of:

table_name — unqualified; the first matching table across all schemas is returned.
schema.table_name — schema-qualified (recommended when the same table name exists in multiple schemas).

Examples: Orders, dbo.Orders, sales.RegionalTotals.

Returns

table

object

Table identity and ownership.

Show table fields

integer

SQL Server object_id.

name

string

Table name.

schema

string

Schema name.

owner

string | null

Principal owner from sys.sysusers, or null.

type

string

Object type code — always U for user tables.

description

string | null

MS_Description extended property value at the table level, or null.

columns

array

Ordered list of columns as returned by sys.columns.

Show column fields

name

string

Column name.

type

string

User data type name (e.g. nvarchar, int, decimal).

length

integer

Maximum byte length (max_length). For nvarchar(max) and varbinary(max) this is -1.

precision

integer

Numeric precision for decimal/numeric columns; 0 for other types.

scale

integer

Numeric scale for decimal/numeric columns; 0 for other types.

nullable

boolean

true if the column allows NULL.

description

string | null

MS_Description extended property at the column level, or null.

indexes

array

Non-primary-key, non-unique-constraint indexes defined on the table.

Show index fields

name

string

Index name.

type

string

Index type description (e.g. CLUSTERED, NONCLUSTERED).

keys

string

Comma-separated list of key column names.

description

string | null

MS_Description extended property, or null.

constraints

array

Primary key and unique constraints from sys.key_constraints.

Show constraint fields

name

string

Constraint name.

type

string

Constraint type description, e.g. PRIMARY_KEY_CONSTRAINT or UNIQUE_CONSTRAINT.

keys

string

Comma-separated list of key column names.

foreignKeys

array

Foreign key relationships in which this table is the parent (referencing) side.

Show foreign key fields

name

string

Foreign key constraint name.

schema

string

Schema of the referencing (parent) table.

table_name

string

Name of the referencing table.

column_name

string

Comma-separated list of referencing column names.

referenced_schema

string

Schema of the referenced table.

referenced_table

string

Name of the referenced table.

referenced_column

string

Comma-separated list of referenced column names.

triggers

array

Table-level DML triggers from sys.triggers.

Show trigger fields

name

string

Trigger name.

is_disabled

boolean

true if the trigger is currently disabled.

is_instead_of_trigger

boolean

true for INSTEAD OF triggers, false for AFTER triggers.

trigger_events

string | null

Comma-separated list of DML event types (e.g. INSERT, UPDATE), or null.

description

string | null

MS_Description extended property, or null.

insight

string | null

Cached AI Insights text for this table. Present only when the Insights layer is enabled (USE_INSIGHTS_LAYER != false). null when no insight has been generated yet.

insightFreshness

string | null

ISO 8601 timestamp of when the cached insight was last written. null when no insight exists.

enrichmentSuggested

boolean | null

true when the Insights layer determines the cached data is incomplete and the agent should enrich it. See the enrichment warning below.

insightEnrichment

object | null

Structured enrichment instructions conforming to the MCP-Insight-Enrichment-v1 protocol. Contains required, nextAction.args, and relatedObjectsToIntrospect. Present only when enrichment is needed.

AI Insights enrichment protocol

MCP-Insight-Enrichment-v1 — mandatory post-call contract. When the response contains insightEnrichment.required=true, or includes a top-level _agentDirective or pendingEnrichments field, agents must call UpsertInsight using the arguments supplied in insightEnrichment.nextAction.args (replacing every <fill in: ...> placeholder with observed values) before producing a final answer.Agents must also inspect every entry in insightEnrichment.relatedObjectsToIntrospect and complete the same enrichment loop for each related object. Skipping this step is a tool-protocol violation and leaves the insight cache stuck at a low-confidence auto-mechanical baseline (confidence 0.30).

For the full enrichment protocol specification, see the Enrichment Protocol reference page.

Example

Request

{
  "tool": "DescribeTable",
  "arguments": {
    "name": "dbo.Orders"
  }
}

Response

{
  "success": true,
  "data": {
    "table": {
      "id": 885578193,
      "name": "Orders",
      "schema": "dbo",
      "owner": "dbo",
      "type": "U",
      "description": "Customer purchase orders."
    },
    "columns": [
      {
        "name": "OrderId",
        "type": "int",
        "length": 4,
        "precision": 10,
        "scale": 0,
        "nullable": false,
        "description": "Primary key."
      },
      {
        "name": "CustomerId",
        "type": "int",
        "length": 4,
        "precision": 10,
        "scale": 0,
        "nullable": false,
        "description": null
      },
      {
        "name": "OrderDate",
        "type": "datetime2",
        "length": 8,
        "precision": 27,
        "scale": 7,
        "nullable": false,
        "description": null
      },
      {
        "name": "TotalAmount",
        "type": "decimal",
        "length": 9,
        "precision": 18,
        "scale": 2,
        "nullable": false,
        "description": null
      }
    ],
    "indexes": [
      {
        "name": "IX_Orders_CustomerId",
        "type": "NONCLUSTERED",
        "keys": "CustomerId",
        "description": null
      }
    ],
    "constraints": [
      {
        "name": "PK_Orders",
        "type": "PRIMARY_KEY_CONSTRAINT",
        "keys": "OrderId"
      }
    ],
    "foreignKeys": [
      {
        "name": "FK_Orders_Customers",
        "schema": "dbo",
        "table_name": "Orders",
        "column_name": "CustomerId",
        "referenced_schema": "dbo",
        "referenced_table": "Customers",
        "referenced_column": "CustomerId"
      }
    ],
    "triggers": [
      {
        "name": "trgOrdersAudit",
        "is_disabled": false,
        "is_instead_of_trigger": false,
        "trigger_events": "INSERT, UPDATE",
        "description": null
      }
    ],
    "insight": null,
    "insightFreshness": null,
    "enrichmentSuggested": null,
    "insightEnrichment": null
  }
}

Overview

Inspection Tools

Write & DDL Tools

Insights Tools

DescribeTable: full metadata for a SQL Server table

Parameter

Returns

AI Insights enrichment protocol

Example

Request

Response

Build docs developers (and LLMs) love

Overview

Inspection Tools

Write & DDL Tools

Insights Tools

Documentation Index

​Parameter

​Returns

​AI Insights enrichment protocol

​Example

​Request

​Response

Build docs developers (and LLMs) love

Parameter

Returns

AI Insights enrichment protocol

Example

Request

Response