frames

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

Annotations carry the safety profile (readOnlyHint=true), and the description adds substantial behavior beyond that: the output is exactly ONE tiled image with frame-number and timestamp stamps, per-frame change is measured, and duplicate frames are reported to catch stutter and frozen output. It also discloses how compare stacks a second sheet underneath in the same image, a non-obvious behavioral trait. No contradiction with the read-only annotation.

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?

Five sentences, each earning its place: core purpose, why the tool exists (models cannot decode mp4), extra detection behavior, parameter workflow, and scope clarification. The core verb-and-output is front-loaded in the first sentence, and no wording is redundant.

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 7-parameter tool with no output schema, the description covers the output artifact, the overview-then-zoom workflow, the compare layout, and the duplicate-detection behavior. The only notable omission is the return value, an agent is not told what the function returns after writing the sheet, though the outdir parameter provides the artifact location.

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?

With 57% schema coverage, the description compensates for the real gaps: to_frame has no schema description at all, and the description explains its purpose alongside from_frame as a zoom into a fraction of a second. It also enriches compare's rationale (before/after needs both sheets in ONE image). However, cols and rows are left to inference from the 'tiled into a contact sheet' context rather than being explained.

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 first sentence states a specific verb-plus-resource: turn a video into ONE image, with N evenly spaced frames stamped with frame number and timestamp, tiled into a contact sheet. It explicitly positions this against the sibling screencast as the other half of screencast, so an agent can distinguish it from the other 32 tools without opening the schema.

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 names screencast as the complementary sibling and states the trigger condition: a model cannot decode an mp4, so a recording is useless until converted to stills. It also prescribes a workflow, use from_frame/to_frame to zoom into a fraction of a second once the overview shows the interesting moment, and scopes applicability with Works on any video, not just screencast output.

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