refresh_sql_endpoint_metadata

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

Despite no annotations, the description discloses the key behavioral traits: it is a long-running operation that must be polled, it syncs FROM the Lakehouse, it drops and recreates tables when recreate_tables is true (destructive behavior), and it requires an env var (FABRIC_MCP_ALLOW_DESTRUCTIVE=1) for the destructive path. This far exceeds the baseline disclosure expected for a tool with zero annotations.

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

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

The description is well-structured: a clear one-line definition, then a note about LRO/polling, then usage guidance, then the parameter list. The content is dense but front-loaded (purpose first, then when to use, then caution). It's slightly verbose but every sentence earns its place. A 4 reflects that it's mostly tight but could condense the final 'sync from the underlying Lakehouse' phrase and the arg descriptions into a shorter form.

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

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

The description gives usage context (schema vs data refreshes), LRO behavior, a destructive flag warning, and the env var requirement for destructive operations. With no annotations providedable, the description steps up and carries nearly all the behavioral burden. It doesn't document the output schema (though output schema exists in the tool definition), and it doesn't explicitly say the endpoint parameter is required—but the schema marks that. Complete enough for an agent to decide when to call and what to expect.

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

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

Schema description coverage is 0%, so the description must add meaning beyond the bare parameter names. It does a reasonable job: workspace and endpoint are self-evident from context ('Refresh metadata for a SQL analytics endpoint'), and recreate_tables is explicitly explained ('drop and recreate all tables...'). However, it doesn't clarify that workspace/endpoint accept either name or GUID (though the Arg docs imply it by saying 'workspace: workspace name or GUID'), so meaning is mostly added. Why not 4? The parameter docs are terse, and no format or enum constraints are provided for the string parameters. 3 is fair because the schema is minimal and the description adds essential meaning for at least the destructive flag.

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

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

The description clearly states the operation: 'refresh metadata for a SQL analytics endpoint, syncing from the underlying Lakehouse.' It names the resource (SQL analytics endpoint) and the specific action (sync metadata), and it differentiates from the sibling tool refresh_table_metadata by noting that this tool handles SCHEMA changes while the sibling handles per-table DATA-only staleness. This is a specific, well-distinguished purpose.

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

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

The description explicitly says when to use this tool ('SCHEMA changes (tables added or dropped)') and when NOT to use it (for cheap per-table data refresh on an existing table, use refresh_table_metadata instead). It also notes the operation is a long-running polled LRO. This is explicit, actionable guidance with alternatives named.

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