Change the timing

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

Annotations already declare mutating but idempotent and non-destructive, so the safety profile is covered. The description adds useful domain semantics (ticks as the length unit, keyframe number = stored pose), but it omits the real behavioral question for this tool: whether changing fps or canvas size rescales existing keyframe timing/content.

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 short sentences, front-loaded with the three modes so an agent knows the shape of the tool immediately. The final sentence about keyframe numbers being stored poses is slightly cryptic but earns its place as disambiguation.

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 an 8-parameter mutation with no output schema, the description covers the three action modes and the key units, and annotations cover reversibility. It still leaves gaps an agent would want: whether the canvas resize affects existing layer positions, and how an fps change interacts with existing keyframe durations.

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 100%, so the baseline is 3; the description goes beyond it by explaining the ticks unit and giving the 24 fps = 24 ticks conversion, which makes the otherwise opaque 'ticks' bound meaningful. It also clarifies that 'frame' refers to a stored pose, disambiguating it from the 'frames' array.

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 gives a specific verb ('change') and enumerates the three concrete resources it operates on: keyframe length, project frame rate, and canvas size, which map directly onto the 'action' enum. It is clear what the tool does, but it never distinguishes itself from the sibling keyframe_edit, which plausibly also touches keyframes.

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?

Usage is implied by the action enum (duration/fps/canvas) and the per-parameter descriptions, but the prose adds no explicit 'use this when' or 'use keyframe_edit instead' guidance. An agent can infer the routing from the enum, but nothing is stated about prerequisites such as an open project or a valid playhead.

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