set_clip_transform

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

With no annotations, the description carries the behavioral burden. It adds useful context: units for pan/tilt, the meaning of zoom = 1.0, opacity range, composite_mode names, scaling values, and that this is a static transform. However, it does not state whether unspecified parameters are left unchanged or reset to defaults, and it omits side effects or prerequisites—important for a 25-parameter setter.

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?

The description is dense but every sentence earns its place: action, id sourcing, unit semantics, ranges, valid values, and the static-vs-animated caveat. It is front-loaded with the core purpose and organized so an agent can scan it quickly despite the large parameter surface.

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 25-parameter tool with no annotations, this is nearly complete: it explains the required id, how to use playhead, parameter units and ranges, valid mode names, and the key alternative tool. It still lacks semantics for crop/anchor/rotation parameters and whether unspecified values are preserved, which prevents a 5.

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 0%, so the description must compensate, and it does for many parameters: pan vs pan_percent, tilt vs tilt_percent, zoom vs zoom_x/zoom_y, opacity range, composite_mode names, scaling modes, and the Resolve mode-name params. Some parameters remain undefined (anchor_x/y, crop_*, rotation, flip_x/y, track_index, dynamic_zoom_ease), so it is not a perfect 5.

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 opens with a specific verb and resource: 'Position, scale, rotate, fade, crop, or blend one timeline item.' It distinguishes itself from sibling tools explicitly by noting this sets a static transform and directing animated zoom to animate_zoom. An agent can tell this apart from get_clip_transform, set_clip_property, and animate_zoom without opening their schemas.

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?

It gives concrete guidance: use an id from timeline_overview or pass item_id='playhead' to avoid a lookup, and for animated scale use animate_zoom instead. It does not discuss when to prefer set_clip_property or get_clip_transform, but the main competing alternative for transform behavior is clearly called out.

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