resolve_set_clip_speed

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

With no annotations, the description carries the full burden and does a decent job. It discloses that the API may reject the request and that it operates on the underlying media-pool property, potentially affecting other uses. This gives important behavioral context about failure modes and side effects, which is valuable for an agent.

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 short (two sentences) and front-loads the caveat, but the wording is vague ('Legacy speed-property request') and could be clearer. It is concise but not optimally structured for quick comprehension of the tool's purpose.

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 tool with three parameters, no annotations, and no parameter documentation, this description is severely incomplete. It omits parameter semantics, expected input formats, and any guidance on success/failure handling. The agent cannot reliably invoke this tool without further external knowledge.

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% and the description provides no explanation of the parameters (speed, clip_index, track_index). The agent cannot determine the expected range or meaning of speed, or how indices are resolved. The description completely fails to compensate for the empty parameter documentation.

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 tool name and description clearly indicate that it sets clip speed ('speed-property request'). It distinguishes itself from siblings by focusing on speed, but the description is framed around legacy status rather than a direct statement of functionality. The purpose is inferable but could be more explicit.

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 warns that the request is legacy and may be rejected, but does not specify when to use it instead of an alternative or provide conditions for usage. It mentions timeline retiming is not guaranteed, which implies caution, but there is no explicit routing to a preferred tool or clear context for when this should be attempted.

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