format_cells

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

With no annotations present, the description carries the full burden, and it delivers meaningful behavioral detail: unspecified attributes are preserved, operations are hazard-gated with an allow_loss override, auto-backup occurs, saves are atomic and verified, and the tool refuses to run while the file is open in Excel. This goes well beyond a bare mutating-tool description and gives an agent accurate risk expectations.

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 well organized: purpose first, then parameter object shapes, then safety behavior. Every sentence earns its place and the semicolon-separated style catalog avoids 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?

For a complex 11-parameter formatting tool with zero schema descriptions and zero annotations, the description covers the core operation, all style object grammar, and critical safety semantics. It is slightly incomplete on positional parameters and the meaning of verify_com, but an output schema exists and the 'design pack' remark clarifies scope limitations.

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 explain parameter meaning, and it does for the key style objects: number_format, font, fill, border, alignment, and color format. It also touches allow_loss ('Hazard-gated') and backup ('auto-backup'), though path, sheet, location, and verify_com are left to general tool-context inference.

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 opens with a specific verb and resource ('Apply formatting to a range') and distinguishes the operation from value-writing siblings by explaining that it merges formatting onto existing styles. It also enumerates exactly which formatting dimensions are covered, so an agent can tell this apart from set_cells/write_range.

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 primary use case is implied by the verb 'Apply formatting' and the detailed style parameter semantics, and the phrase 'Named styles and conditional formats: design pack' hints at an exclusion for those features. However, there is no explicit when-to-use or when-not-to-use statement, and no alternative sibling is named for comparison.

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