audit_video_playback

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, lowering the bar. The description adds genuinely valuable behavioral context beyond annotations: it uses headless Chromium, samples currentTime before and after a play() attempt, and produces a classification. It fully explains the two paths (live render vs. deterministic classification) and contradicts nothing.

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 sentences, all dense with distinct information: the mechanism (multiply, currentTime, play attempt + classification set), the value proposition (catches what static audits miss, with domain context), and the parameter usage. Every sentence earns its place; nothing is repeated from the schema.

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 compensates well for the lack of an output schema by naming the classification categories and the observation method. It covers both potential invocation paths. The remaining gap is the exact return format (how classifications and reasons are represented) — but with a well-endowed schema and read-only annotations, the overall context is complete enough for a capable agent.

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 schema already documents all three parameters (url, observeMs, dom_snapshot) with detail. The description goes beyond schema by revealing that url and dom_snapshot are alternative, mutually exclusive entry points — one requires a browser render, the other is a deterministic path without a browser. That relationship is not in the schema and is materially useful to an agent.

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 names a specific verb/resource pair ('render a page... observe whether each <video> actually advances') and precisely delimits the output: each clip classified into playing|paused|stalled|empty|error with a reason. It clearly distinguishes itself from static audit siblings, which it claims to complement by catching black/non-playing videos that static audits miss.

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 provides a clear usage context ('catches black/non-playing videos that static audits miss — the most common real-world defect on marketing sites with video content'), which is an implicit when-to-use signal against static audit alternatives. It also explains the two calling modes within the tool: url-based rendering and snappable deterministic dom_snapshot input. It does not name a specific alternative tool and does not state when NOT to use it, so it is not a 5.

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