Plan Emphasis Zoom Keyframes

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds genuine value by stating it is 'Local-only and deterministic', that it returns a plan rather than applying changes, and explicitly that it 'never changes Premiere' — all consistent with the annotations. It does not cover edge-case behaviors like trigger dropping, but those are documented in the schema, so the added context is sufficient.

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?

Two dense sentences with zero filler: the first front-loads the verb and resource while enumerating inputs and controls, and the second delivers the behavioral guarantees and downstream consumers. Every clause earns its place, and the description wisely leaves parameter minutiae to the 100%-covered schema.

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 17-parameter tool with nested objects, the combination of annotations (read-only, idempotent, non-destructive) and an output schema relieves the description of explaining return values. The description covers what the tool produces, its input modes, its safety profile, and how its output is consumed. Nothing an agent needs to decide whether and how to call it correctly is missing.

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 schema's per-parameter descriptions already document defaults, bounds, and relationships (e.g., zoom_scale must exceed base_scale). The description adds only a high-level grouping of 'cooldown, easing, and hold controls' and the two input modes, which is useful orientation but not additional semantic detail. With 17 parameters fully covered in the schema, no compensation is needed.

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 states a specific verb and resource: 'Plan CapCut-style punch-in zoom keyframes (Motion Scale + subject-anchored Position)', which is unique among the large sibling list. It further specifies the input sources ('word timeline or supplied trigger times'), the configurable controls ('cooldown, easing, and hold'), and the downstream consumers ('automate_effect_parameters_uxp or add_keyframe'), making it fully distinguishable from every other plan_* sibling.

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 gives clear context that this is a planning step whose output feeds automate_effect_parameters_uxp or add_keyframe, and that it is 'Local-only and deterministic' and 'never changes Premiere', signaling it is safe to run as a preview before any application step. However, it does not explicitly name an alternative tool and state the condition for choosing it over that alternative (when-not-to-use guidance), which keeps it slightly below the strongest examples.

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