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

Goes well beyond the annotations by disclosing that apply performs "no render, one undoable change per clip (undo_edit)" — a critical reversibility fact for a destructiveHint=true tool. It also documents the two-phase delete protocol (first call returns a confirm token plus a question, second call with `confirm`) and the `replace` overwrite semantics, which are exactly the safety details annotations cannot convey.

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 when-to-use sentence and then organized loosely by action, and nearly every clause carries new information (kind meanings, settings shapes, confirm flow). It is a single dense run-on block, though, which makes it harder to scan than a short per-action breakdown would be.

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 13-parameter, six-action tool with an output schema, the description covers each action's inputs, the kind taxonomy, and the delete confirmation loop. It omits error/failure behavior (e.g. applying a nonexistent id, or what happens if a `replace` is not set on a name collision), which would matter for a mutation tool.

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 already 85%, but the description adds real meaning: per-kind `settings` payload shapes with a concrete example ({"style":"bold-punch","color":"#ffffff","font":"Anton"}) and the title fields, plus the three alternative targets for apply (clip_id, clip_ids, episode_id). Only marginal gaps remain, such as clip_id vs clip_ids precedence.

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?

States a specific resource (saved templates) and enumerates each verb the tool performs: save, list, get, apply, rename, delete. It also anchors the concept to user-facing vocabulary ("the same saved templates as the Slice editor's Saved styles") and breaks down every enum value of `kind`, so an agent can distinguish this from siblings like list_styles or get_visual_style.

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?

"Use this when the person likes a look and wants to keep it, or wants their saved look on clips" gives a clear triggering context, and the apply/save clauses add conditions (e.g. `new_uploads` only "when the person asks"). However, it never explicitly excludes the nearest siblings (list_styles, restyle_clip, get_visual_style), so the agent must infer when a one-off restyle is preferable to saving a template.

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