clear_range

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

With no annotations, the description carries the full behavioral burden, and it delivers thoroughly: it explains destructive scope, hazardous workbook refusal, allow_loss requirements, auto-backup behavior with rotation, atomic verified saves, restore on failed verification, and refusal while open in Excel.

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 dense but every sentence adds essential information. It front-loads the core operation and then efficiently covers exclusions, hazards, backup behavior, and lock conditions without redundancy.

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 tool's destructive nature and the absence of annotations, the description is remarkably complete. It covers what gets cleared, what persists, safety guards, backup semantics, failure recovery, and environment restrictions. An output schema exists, so return-value documentation is not required here.

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. It explains the 'what', 'backup', 'allow_loss', and 'location' parameters meaningfully. However, 'path', 'sheet', and especially 'verify_com' are not explained, leaving some parameters underspecified.

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 the tool clears a cell or range and precisely defines the three 'what' modes: contents, formats, and all. It also distinguishes what the tool does not remove, eliminating ambiguity about scope.

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 gives practical usage context: it clarifies that merges, conditional formats, validations, comments, and hyperlinks are not handled here and have their own manage tools. It also states important refusal conditions, but it does not explicitly name sibling alternatives or contrast with related tools like write_range or set_cell.

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