set_cells_block

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

With no annotations, the description carries the full burden and does substantial work: auto-backup behavior, backup=False semantics, atomic validated save, and refusal to modify Word-locked documents. The backup slot path and 'rotation only' detail add real behavioral context, though 'prev/anchor slots' is somewhat opaque.

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 dense sentences with no filler. The primary operation and alternative are front-loaded, followed by backup and safety behavior. Every sentence contributes information an agent needs.

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 an output schema exists and no annotations are present, the description covers the key operational traits: block semantics, backup behavior, atomicity, and document lock refusal. It is complete enough for an agent to select and invoke the tool safely, though some details like coordinate bounds are left unspecified.

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 clarifies origin_row/origin_cell as the starting coordinates, data as a 2D block of values, and backup's behavioral meaning. file_path and table_index are not elaborated but are sufficiently self-descriptive from their names and schema structure.

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: 'Write a 2D block of values starting at (origin_row, origin_cell)'. It clearly distinguishes itself from set_cells by describing the block write vs scattered single-cell edit use case.

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?

Explicitly routes the agent: 'for scattered single-cell edits use set_cells'. This is a direct when-to-use vs alternative instruction, and the Word lock refusal adds another usage boundary.

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