list_violations

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context about advisory semantics, host UI warning markers, and the pull-based polling rationale. However, the phrase 'return every cell' is slightly at odds with the `limit` parameter default of 50, so the limit's effect is not fully disclosed.

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?

Well-organized into three short paragraphs: purpose, when-to-use, and filter/polling behavior. Every sentence contributes; the pull-based rationale is relevant for an LLM agent deciding whether to poll or rely on push.

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?

Covers purpose, usage triggers, filter composition, advisory semantics, and polling rationale. Gaps remain around the exact return shape and how `limit` interacts with the 'every cell' promise, and there is no output schema to fill those gaps.

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 covers 2/3 parameters (block and sheet) with descriptions; the description adds 'omit both... to scan the whole workbook; pass either to narrow,' clarifying filter composition. The `limit` parameter receives no additional semantics beyond the schema's default/minimum, and the 'every cell' wording makes the cap less clear.

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+resource: 'Scan validation shadow cells and return every cell whose validation formula currently evaluates FALSE.' It clearly distinguishes this from sibling tools like get_cells or eval_formula by focusing specifically on validation failures.

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 states when to use: 'Use this when answering why is something red?, what's broken after my last edit?, or before committing a multi-step build...' It also explains filter composition and how to omit or pass block/sheet to narrow the scan.

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