Delete a chart

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds a genuinely new trait: the deletion cannot be reversed through undo_last, which is not captured by the annotations and directly affects agent risk assessment. It does not cover permission requirements or side effects on the spreadsheet beyond the chart.

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?

Two short sentences, no filler, with the core action first and the two operational facts (id provenance, irreversibility) following. Every clause carries load.

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 destructive, no-output-schema operation the description supplies the essentials: what it does, where the id comes from, and that it is irreversible. Minor gaps remain on whether the spreadsheet must be open or what happens to the surrounding sheet data, but nothing critical to invoking it is missing.

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 67%: account and spreadsheet are documented in-schema, but chart_id has no schema description. The description compensates by explaining exactly where valid chart ids come from, which is the key missing piece. This is above the baseline-3 case where the schema does all the work.

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?

States a specific verb and resource ("Delete a chart") and names where the required chart_id originates (get_spreadsheet_info or add_chart), which pins down the operation precisely. The verb clearly separates it from add_chart and update_chart, though it does not explicitly contrast itself with those siblings.

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?

Provides a concrete prerequisite path for obtaining the required chart_id (get_spreadsheet_info or add_chart) and a caution that the action is not recoverable via undo_last, which shapes when an agent should commit to calling it. It stops short of an explicit "use this instead of X when Y" statement.

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