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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the operation can overwrite an existing keyframe, that the curve is anchored to the clip, that moving the clip carries the ramp without changing duration, that rate multiplies the layer's constant speed, and that timeline length derives from the curve. This is comprehensive and non-obvious behavioral context.

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, starting with the core action and immediately clarifying the change-over-time behavior, then addressing the key timing constraint, the constant-speed alternative, and rate semantics. No filler or redundant restatement of the 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?

Given the tool's complexity, the absence of annotations, and the lack of an output schema, the description is remarkably complete. It tells the agent what the tool does, when to use it, what constraints exist, how parameters behave, and what side effects occur. No critical usage information 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?

Although the schema covers all four parameters at 100%, the description adds substantial meaning beyond the schema: frame must be at or after timeline_start_frame, the curve anchors to the clip, rate values map to real-time/half-speed/double-speed, and the clip's timeline length is derived from the curve. This significantly enhances an agent's ability to pick correct parameter values.

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 names a specific verb and resource: 'Add or overwrite a speed-ramp (time-remap) keyframe on a video layer.' It also clarifies the key differentiator, that the rate changes over the clip, and explicitly contrasts this with set_clip_speed for constant speed changes. An agent can immediately identify what this tool does and why it exists.

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 explicitly tells the agent when to use this tool versus an alternative: 'For a constant slower/faster clip use set_clip_speed instead.' It also states the frame must be a project-timeline frame and must sit on the clip, giving clear positional requirements for invocation.

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