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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent, closed world), so the bar is lower. The description adds that motion can be inferred from a detected face, image geometry, or an explicit treatment, which is genuinely useful. It omits whether an existing motion is replaced versus compounded and what the "archive" treatment does — a notable gap given the non-idempotent write hint, and "adds or updates" sits in mild tension with idempotentHint=false.

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?

A single front-loaded sentence with no filler; the primary action and subject come first, qualification second. It is efficient, though its brevity leaves the parameter gaps noted elsewhere.

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?

A nine-parameter mutation tool with no output schema and near-zero schema documentation deserves substantially more explanation than one sentence. An agent must guess at fit, ease, amount, path, and treatment behavior, and gets no signal about what state changes on success or how to verify the result.

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 only 11% — eight of nine parameters are bare, four of them enums with no explanation of what the values mean (fit, ease, path, treatment). The phrase "face, image geometry or explicit motion treatment" vaguely gestures at path=auto, focus_x/focus_y, and treatment, but never ties semantics to any named parameter, and amount's 0.03–0.4 range, ease modes, and fit modes go entirely unexplained.

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?

"Adds or updates camera movement for a still-image overlay or insert" names a specific verb and resource, and the trailing clause explains what drives the movement (face, geometry, or treatment). It is clearly distinguishable from sibling adders like add_zoom or add_overlay, though it never names a sibling it differs from. A reader knows what the tool produces but not precisely how it relates to set_overlay_motion or add_zoom_path.

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?

There is no when-to-use guidance, no prerequisites, and no routing to alternatives, despite several plausible competitors in the sibling list (set_overlay_motion, add_zoom_path, add_zoom, add_motion_graphic). Only the implicit constraint that the subject is a still-image overlay or insert narrows the use case.

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