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

Annotations already declare a non-read-only, non-destructive, non-idempotent, closed-world write, so mutation is covered. The description adds real context the annotations cannot: exactly what state is captured, that the template appears in Templates, that look_from saves only captions and layout and is Premium-gated, that for_new_clips also rewrites the default clipping preset applied by find_clips and clip_range, and that it costs no Horizon Units. It does not discuss whether re-saving an existing name overwrites or duplicates, which matters for a non-idempotent write.

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?

Front-loaded with the user intents before any parameter talk, and organised parameter-by-parameter with short colon-led clauses. It is dense and long, but nearly every clause carries decision-relevant information; a few phrasings (repeating the trigger phrases for for_new_clips) could be trimmed.

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?

An output schema exists, so return values need not be explained, and the description still adds the post-save next step. For a six-parameter write with branching modes (clip_id vs look_from) and a side effect (default preset), the only real gap is what happens on name collision or invalid link.

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 0%, so the description carries the full burden, and it does so for every parameter: name length cap (60 characters), clip_id source (list_clips), the allowed category values plus edit_catalog as the lookup path, description as optional, for_new_clips semantics with example trigger words, and that look_from takes a TikTok/YouTube link and needs no clip_id. Only the exact expected URL form and behaviour on an invalid link are left implicit.

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?

Specific verb and resource: "Saves the clip's whole edit (format and layout, captions, colour, effects, transitions, music, text and sounds) as one of the user's templates". It explicitly distinguishes itself from the nearest sibling (style_clip) and names where the result surfaces (Templates in RipClip).

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?

Gives concrete user phrasings that trigger it ("save this style", "remember this edit"), an explicit "Not for:" clause routing to style_clip for applying a style or a single caption style, and "Ask if unclear" for the for_new_clips decision. The follow-up step ("Next: style_clip(template=...) on other clips") closes the loop.

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