video_shape_mask

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

With no annotations at all, the description carries the full burden, yet key behavioral facts are absent: what happens to pixels outside the shape (transparent, black fill, or crop), whether audio and codec settings are preserved, and how the 'overwrite' guard behaves. It does disclose that output_path is auto-generated when omitted and that feather=0 means sharp edges, which is genuinely useful but not enough for a file-writing mutation tool.

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?

One front-loaded sentence establishes the operation, followed by a tight per-argument list where every line adds information the schema lacks. No filler or restated boilerplate.

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?

An output schema exists, so return values need not be explained, and the parameter list is reasonably covered. For a video-mutating tool with zero annotations, though, the missing explanation of mask semantics (what fills the region outside the shape) and overwrite behavior leaves a real gap.

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 only 20%, so the description must compensate, and it largely does: it supplies the three allowed shape values (the schema declares no enum), explains feather as a pixel radius with 0 = sharp, and notes that output_path auto-generates. Only 'overwrite' is undocumented here, though the schema itself carries a description for it.

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?

A specific verb plus resource ('Apply a geometric shape mask to a video') that an agent can act on without opening the schema. It does not, however, distinguish itself from close siblings such as video_apply_mask, video_luma_key, or effect_vignette, which could plausibly do overlapping work.

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 states what the tool does but never when to reach for it versus video_apply_mask or the keying/vignette effect tools, and lists no prerequisites. The only implicit guidance is the shape enumeration, which falls short of actual when-to-use direction.

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