preview_changes

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

The annotations already declare readOnlyHint=true and destructiveHint=false ya, but the description adds meaningful behavioral detail: writes go to a temp branch that is discarded, and it highlights a potential large-response performance pitfall (416 rows of diff). This is exactly the kind of context that helps an agent avoid surprises beyond the annotation hints.

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?

Three tightly-packed paragraphs, each earning its place: 1) core behavior and safety, 2) two modes, 3) output-size optimization. Front-loaded with the most important 'dry-run/safe' concept. No fluff, but the description is dense and requires some parsing; still efficiently structured.

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 tool with 3 params and no output schema, the description covers the modes (`changes` vs `scenarios`), how to interpret results (returns what would move, including cascades), and the `watch` parameter's purpose and advantage. It doesn't describe the exact return shape, but given dense schema descriptions, this is sufficient and complete for the complexity.

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 coverage is 100%: `watch` says 'report only these cells' values instead of the full diff', `changes` 'one hypothetical... use `scenarios` for more', and each field has a description. The description complements it by explaining the semantic vs coordinate addressing for `watch` and the notion of 'cascaded recalculations' which clarifies that the diff includes more than direct writes. Builds on schema, adds value.

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 starts with a specific verb+resource ('Dry-run edits on the workbook'), states what it reports (what they would do), and explicitly contrasts with actual changes ('Nothing is committed'). It clearly distinguishes two operational shapes (changes vs scenarios) and mentions the optional watch filter, all in the first sentence. This strongly separates it from sibling tools.

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 frames this as 'the safe way to explore' instead of changing and putting it back, giving clear when-to-use context. It also explains when to use `watch` vs. getting the whole cascade incl. an explicit example of a large scenario grid. The schema reinforces with `scenarios` 'use `changes` for one.' Guidance is explicit and immediate.

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