pixel_onion_view

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

Discloses key behavioral traits beyond annotations: 'Nothing is written to disk', opacity percentages (35%, 20%, 12%), ordering of ghosts, tint effect for silhouettes, and return format ('text summary plus the rendered image', 'Error: ...' on failure). Annotations already indicate readOnly and idempotent, but description adds concrete details.

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 succinct sentences covering purpose, ordering/opacity, tint, safety (no disk writes), and return/failure format. No redundant information; every sentence adds value.

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 return value (text summary + image), error format, and core logic for a 4-parameter tool with no output schema. However, does not mention the 'scale' parameter or auto-fit behavior, which would help a user understand display size control. Overall adequate but slightly incomplete.

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?

Description adds meaning for 'previous_paths' (most-recent-first ordering, fading percentages) and 'tint' (silhouettes, prevents color overlap). However, 'scale' is not mentioned despite being optional with auto-fit behavior. Given 0% schema description coverage, the description compensates partially but not fully for all parameters.

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?

Description clearly states 'Render the current frame over faded ghosts of up to 3 earlier frames — onion-skinning, the standard way to judge motion between animation frames.' The verb 'render' and specific resource 'current frame over faded ghosts' precisely define the action, and the purpose 'judge motion' distinguishes it from siblings like pixel_view_canvas.

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 implies usage when needing to judge motion between animation frames ('standard way to judge motion'). It provides context but does not explicitly exclude alternative tools or state when not to use it. Sibling pixel_view_canvas exists but is not contrasted.

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