refresh_table_metadata

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is mutating but NOT destructive, that it respects FABRIC_MCP_READONLY, that it does not require FABRIC_MCP_ALLOW_DESTRUCTIVE, that it raises ToolError for missing tables/permissions/type rejections, and that the driver does not distinguish missing vs permission-denied. This is exceptionally transparent about side effects 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.

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

The description is long but every sentence earns its place: it covers scope, alternatives, prerequisites, safety profile, and error behavior. It is front-loaded with the core purpose and the key distinction from the sibling. Slightly verbose in the error-handling paragraph, but the density of useful information justifies the length.

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?

For a mutating tool with no annotations and 0% schema coverage, the description covers everything an agent needs: when to use it, when not to, prerequisites, safety profile, parameter semantics, and failure modes. The output schema exists, so return values need not be described. The only minor gap is not describing the success return value, but that is covered by the output schema.

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 compensate. It explains workspace (name or GUID), item (SQL Analytics Endpoint name or GUID, Data Warehouses rejected), and qualified_name (dot-separated, e.g. dbo.sales, must already exist). It doesn't give exact formats for workspace/item GUIDs, but the examples and constraints add substantial meaning beyond the bare schema.

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 states a specific verb and resource ('Refresh one table's metadata via sys.sp_dw_refresh_ext_table') and immediately distinguishes it from the sibling refresh_sql_endpoint_metadata by scope (DATA-only staleness vs SCHEMA changes). It also names the exact stored procedure, leaving no ambiguity about what the tool does.

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 (per-table, DATA-only staleness) and when NOT to use it (schema changes), naming the alternative refresh_sql_endpoint_metadata. It also gives platform prerequisites (SQL Analytics Endpoints only, not Data Warehouses, and only after 'New metadata sync' preview setting) and error-handling guidance for missing tables, permissions, and type-based rejections.

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