Capture motion over time

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

Annotations already signal that the tool is not read-only, not idempotent, and operates in an open world; the description adds behavioral context by specifying the capture mechanism (frame-strip sampled over time after load/scroll/hover/click), the inventory data (keyframes, timing, easing, play state), and per-frame numeric curves. It also highlights the key limitation it overcomes — JS-driven animation invisible to static analysis. No contradiction with annotations is present.

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 information-dense sentences with no filler; the core capability is front-loaded in the first sentence and the key differentiator is delivered in the second. Every clause either defines an output mode or a selection criterion, making it efficient for an agent to process.

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?

Despite 16 parameters, the description covers the tool's output modes and differentiates it from its nearest sibling while the schema supplies parameter-level detail. Minor operational context such as filesystem side effects from outputDir or explicit prerequisites is absent, but that does not block correct tool selection or initial configuration.

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 baseline is 3; the description adds semantic grouping by mapping 'sampled over time' to samples/intervalMs, the trigger list to trigger/selector, the WAAPI inventory to maxAnimations, and numeric curves to trackSelectors/maxTrackedElements. This helps an agent infer parameter relationships without needing to parse every schema field, though it stops short of adding syntax-level detail.

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 object — 'Capture how a page actually moves' — and then enumerates three concrete outputs: a sampled frame-strip, a Web Animations API inventory, and per-frame numeric transform/opacity curves. This precision lets an agent distinguish it from static-analysis siblings like extract_animations and from a single capture_screenshot.

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 closing sentence explicitly positions the tool against extract_animations: it catches JS-driven motion (GSAP, Framer Motion) that extract_animations cannot see statically, giving an agent a clear condition for choosing this tool. It does not, however, provide exclusion criteria relative to capture_interactions or capture_screenshot, so some usage boundaries remain implicit.

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