Add a pivot table

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description adds the key side-effect disclosure that a new tab is created unless anchor_cell is given, and warns of the anchor-cell area constraints implied by the schema. Adds write-location context beyond the security profile.

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 tight sentences, front-loaded with purpose, then placement behavior, then the prerequisite. No repetition of schema fields; every clause earns its place.

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 9-parameter mutation tool with no output schema, the description covers purpose, side effects, and prerequisites adequately. Minor gap: it doesn't clarify that show_totals/new_tab_name interact with the default placement, though the schema implies this.

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 78%, so the schema carries most parameter detail, but the description adds genuine semantics: that columns may be referenced by header name or letter and that a header row is required — neither stated in the schema itself. This meaningfully reduces invocation error.

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?

Specific verb+resource: "Summarize a table with a pivot table." No sibling tool creates pivot tables, so the purpose is immediately unambiguous and distinguishable from add_chart, set_filter, and sort_range.

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?

Description gives concrete prerequisites (source range needs a header row, columns referenced by header name or letter) and states the default placement (new tab vs anchor_cell). It lacks explicit when-not-to-use guidance, but no sibling competes for this task.

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