delete-excel-range

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

The description goes beyond the destructiveHint annotation by explaining that deletion shifts remaining content and that the shift direction is controlled via the body. It doesn't mention side effects like irreversibility or the confirmation gate, but the destructive annotation already covers the core risk, and the shift behavior is a useful addition.

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 concise and front-loaded with the core action, followed by a helpful tip. There's no redundant text, and the format makes the key information easy to find. Slightly informal due to the emoji, but that doesn't detract.

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 operation with multiple required identifiers, the description covers the main behavior and the critical shift parameter, but it doesn't address the confirmation mechanism (though it's in the schema) or provide examples for the address format. It's adequate but not exhaustive, leaving a few gaps for an agent to fill.

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 high (88%), and the description adds meaningful semantics for the body.shift parameter by explaining the allowed values ('Up'/'Left') and that 'Up' deletes entire rows. Other parameters (driveId, address, etc.) are adequately described in the schema, so the description's extra detail for shift is valuable.

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 clearly states that the tool deletes an Excel range and specifies that it shifts remaining content, which distinguishes it from a plain clear operation. It doesn't explicitly name sibling tools like clear-excel-range, but the behavior is enough to infer the purpose.

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 tip implies the tool is for deletion with shifting, and specifically mentions using 'Up' to delete entire rows. However, it does not explicitly state when to choose this over alternative range operations (e.g., clear-excel-range) or provide exclusions, leaving the usage guidance somewhat implicit.

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