Clear values

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

Annotations already flag destructive=true and readOnly=false, but the description adds valuable beyond-annotation context: 'no undo through the API' and the precise closure that formatting, data validation, notes, conditional formats, and merges all stay. This materially expands what the agent knows about side effects and postcondition state. There is no contradiction with annotations.

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 two sentences with zero filler, front-loading the core semantics first and then routing edge cases to alternatives. Every clause earns its place by either refining behavior or disambiguating siblings.

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 destructive mutation tool with no output schema, the description tells the agent what happens, what does not happen, that it is irreversible, and which sibling to choose for nearby operations. Combined with the fully covered schema and clear annotations, nothing needed to call this tool correctly is missing.

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 100%, so the schema already fully documents both parameters, including the A1-notation examples and the spreadsheet URL format. The description's 'one or more A1 ranges in a single call' adds process context but not new parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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 ('Empties the VALUES of one or more A1 ranges') and precisely scopes what is affected: cell contents and formulas are removed while formatting, validation, notes, conditional formats, and merges are preserved. This clearly distinguishes the tool from siblings like format_cells, manage_dimensions, and raw_request.

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 explicitly names the alternatives for adjacent use cases: 'To also remove formatting use format_cells or raw_request; to delete whole rows/columns... use manage_dimensions action=delete.' This makes the selection criteria concrete and leaves no inference about when clear_values is or is not the right tool.

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