fabric-dw-mcp-cli

Overview Schema Source Related Servers Discussions Admin

list_table_sync_status

Shows per-table metadata sync freshness for SQL Analytics Endpoints, flagging tables absent from the catalog and cross-checking Lakehouse inventory to uncover undiscovered tables.

Instructions

Show per-table metadata sync freshness via sys.dm_db_external_tables_log_status.

Only supported on SQL Analytics Endpoints (not Data Warehouses), and only on endpoints created after the workspace's 'New metadata sync' (preview) setting was enabled. A table with no matching DMV row still appears, with its sync fields null instead of the row being dropped -- this means no sync information is available for that table, NOT that it has never synced; do not treat a null row as proof the table has never synced.

IMPORTANT for agents: by default this listing only includes tables already present in the endpoint's catalog (sys.tables), which is itself maintained by the metadata sync. A Lakehouse table whose discovery has not completed, or has failed, has no catalog row and so is absent from this result entirely -- it will not appear as a row with empty fields, it simply will not be there. Do not conclude a table does not exist, or was deleted, just because it is missing from this list.

Pass check_lakehouse=True to close part of that gap: it cross-references the backing Lakehouse's own table inventory (one or more extra REST calls -- avoid setting this on every call of a tool an agent may invoke repeatedly) and adds a row with in_endpoint_catalog=false and all sync fields null for every table it finds there but not in the catalog, comparing names exactly (case-sensitively, matching Fabric's default collation). A Lakehouse table that differs from a catalog table only by case gets case_mismatched_catalog_name set to that catalog name instead of being reported as a flat miss.

This works for both classic and schema-enabled Lakehouse-backed endpoints (the schema-enabled path uses a preview OneLake table API). If the endpoint's backing item cannot be resolved to a Lakehouse at all (a mirrored database, or similar), check_lakehouse=True raises a ToolError explaining why, rather than silently returning the unchanged catalog-only result: a caller that explicitly asked for this cross-check must never read "no extra rows" as "fully discovered". check_lakehouse=True also cannot be combined with schema or table (raises a ToolError): it always compares the whole endpoint. If check_lakehouse=True fails or an expected table is still missing after trying it, call refresh_sql_endpoint_metadata (or tell the user to run fdw sql-endpoints refresh) to force an item-level sync, then check again.

Args: workspace: Workspace name or GUID. item: SQL Analytics Endpoint name or GUID. Data Warehouses are rejected with a ToolError. schema: When provided, only tables in this schema are returned. table: When provided, filter to this single (bare, unqualified) table name. Requires schema to also be given. check_lakehouse: When True, cross-reference the backing Lakehouse's table inventory for tables missing from the endpoint catalog entirely. See above for its limits. Mutually exclusive with schema and table.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`item`	Yes
`table`	No
`schema`	No
`workspace`	Yes
`check_lakehouse`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2026.9.0Sep 9, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels. It discloses that null sync fields mean 'no sync information available' rather than 'never synced', that tables missing from the catalog are absent entirely rather than appearing as null rows, that check_lakehouse=True makes extra REST calls, that it raises ToolError on unsupported backing items, and that case mismatches are handled specially. This is exceptionally transparent about edge cases and failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: the core purpose is front-loaded, followed by critical caveats, then the optional flag behavior, then parameter details. The 'IMPORTANT for agents' section is clearly marked and the parameter list is structured. It loses one point only because the length is substantial and some caveats could arguably be condensed, but the density of critical information justifies most of the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 5 parameters, no annotations, and an output schema, the description is remarkably complete. It covers supported environments, failure modes, edge cases (null rows, absent rows, case mismatches), performance implications, mutual exclusions, and follow-up actions. The output schema exists, so return values need not be described. Nothing an agent needs to call this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the schema's bare parameter names, and it does thoroughly. It explains that workspace is a name or GUID, item is a SQL Analytics Endpoint name or GUID (with Data Warehouses rejected), schema filters to a schema, table requires schema to also be given, and check_lakehouse cross-references the Lakehouse inventory with mutual exclusivity constraints. Every parameter's semantics are fully explained beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Show per-table metadata sync freshness via sys.dm_db_external_tables_log_status.' It clearly distinguishes this from sibling tools like refresh_sql_endpoint_metadata and list_tables by focusing on sync freshness rather than table listing or refresh actions. The scope (SQL Analytics Endpoints only) is stated immediately, making the tool's purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: it states the tool is only supported on SQL Analytics Endpoints (not Data Warehouses), explains when check_lakehouse=True should be used, and explicitly names the alternative tool (refresh_sql_endpoint_metadata) to call when an expected table is still missing. It also warns against setting check_lakehouse on every call due to extra REST calls, giving clear usage boundaries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server