set_cluster_columns

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

With no annotations provided, the description carries the full behavioral burden and does so exceptionally: it details the transactional CTAS-swap steps, automatic rollback on failure, full-table copy cost, and the fact that dependent views and stored procedures are not automatically updated. It also clarifies that null or an empty list removes clustering.

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 front-loaded with the core purpose, then uses numbered steps for the swap process, followed by the transaction guarantee, cautions, and support constraint. Every section earns its place and is organized for quick scanning by an agent.

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?

Given the destructive/rebuild complexity and zero parameter descriptions in the schema, the description is remarkably complete: it covers operational mechanics, failure safety, performance implications, dependent-object caveats, support boundaries, and parameter semantics. Since an output schema exists, omitting return value details is acceptable.

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, and it does for all four parameters. It explains workspace and item as names/GUIDs, defines qualified_name as a dot-separated table name like dbo.sales, and specifies cluster_by limits to up to 4 columns with null/empty-list behavior.

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 first sentence states a specific verb and resource: 'Change (or remove) the data-clustering columns of an existing table.' This clearly distinguishes the tool from siblings like get_cluster_columns and create_table by covering both setting and removal of clustering on an existing table.

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 clearly indicates when the tool applies: for an existing table needing cluster column changes, with an explicit exclusion that it is only supported on Fabric Data Warehouses and not SQL Analytics Endpoints. It does not explicitly name alternative tools for inspecting or rebuilding tables, but the scope and support constraints are clear.

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