Format cells

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

It discloses the key behavioral guarantee: 'Only the provided properties are touched — the update mask is computed automatically, so existing formatting outside it survives,' which goes beyond the readOnly/destructive/idempotent annotations. It also clarifies that formatting fields must be supplied and that range coordinates are 0-based. It does not discuss return or error behavior, but the annotations cover the main safety profile.

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 core action and most important side-effect ('only provided properties are touched') are front-loaded. The first sentence is a long enumeration, but that is acceptable given the breadth of 15 formatting parameters.

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?

The description covers selection, update behavior, range addressing, required-field constraints, and color format, which is substantial for a mutating formatting tool with no output schema. Remaining omissions such as return value and potential errors are minor against the fully documented input schema and annotations.

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 100%, so the baseline is 3, but the description adds meaning beyond individual field docs: it explains the automatic update mask, the requirement to provide at least one formatting field, and the '#RRGGBB' color convention. This helps the agent understand which optional parameters form a valid call.

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: 'Applies cell formatting to a range,' then enumerates all supported formatting categories such as background color, font styles, alignment, wrap, and number format. This makes it easy to distinguish from sibling tools like write_values, set_borders, and clear_values.

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 clearly signals this is the tool for styling cells rather than writing values or managing sheets, and adds a concrete validity constraint: 'at least one formatting field is required.' It does not explicitly name alternative tools or state when not to use it, but the context is strong enough for correct selection.

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