write_range

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

With no annotations, the description carries full behavioral burden and does so thoroughly. It discloses ragged-row refusal, null-padding clearing behavior, formula normalization, recalculation flagging, grid limits, the 200,000-cell ceiling, hazardous workbook refusal, allow_loss behavior, auto-backup, atomic verified save, 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 carries a distinct behavioral or safety constraint. It is front-loaded with the primary action and follows with high-value details, with no filler or repetition.

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 7-parameter mutating tool with no annotations, the description is unusually complete: data format, limits, failure modes, persistence, and safety are all covered. Minor gaps remain around verify_com and sheet selection, but an output schema exists and the core calling contract is well specified.

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 0%, so the description must compensate. It explains data as a list of row lists that must be rectangular, describes location as the top-left anchor, clarifies allow_loss for hazardous workbooks, and mentions backup behavior. However, it does not explain verify_com or sheet semantics.

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?

Description opens with a specific verb and resource: 'Write a 2D block of values and formulas anchored at the location's top-left cell.' It also scopes the operation by noting content outside the block is never touched, which clearly differentiates it from single-cell and other range tools like set_cell, set_formula, and apply_edits.

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?

Usage context is implied through the 2D-block description and constraints like ragged-row refusal, but there is no explicit when-to-use versus when-not-to-use guidance or named alternatives. An agent can infer the intended use case but is not explicitly routed away from sibling tools.

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