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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses that it bills a render against the project's image or video model, that it sits outside any run's cap, and that a human approval gate applies. It also explains idempotency semantics including the retry-with-same-key rule, which is exactly the behavioral context an agent needs before a costly mutation.

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 cost warning and core action are front-loaded and nearly every clause carries new information (cost, cap exemption, approval, key provenance, idempotency). The final sentence is long and slightly run-on, costing a point on structure.

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?

With no output schema and a destructive, credit-spending mutation, the description covers cost, approval gate, cap exemption, retry safety, and input provenance — everything an agent needs to call it without causing double billing or unauthorized spend.

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 only 20%, so the description must compensate, and it largely does: it explains note as image-only change instructions with an example, gives asset_key provenance, and fully specifies idempotency_key behavior. The kind enum values are only partly reflected in prose (look/storyboard frame/clip vs. six enum values) and project_id is unaddressed, keeping it below 5.

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 first sentence gives a specific verb+resource+scope: redo one asset (look, storyboard frame, clip) rather than a whole plan or run, which implicitly separates it from siblings like apply_plan and run_control. It does not name an alternative tool explicitly, so it falls short of a 5.

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?

Explicit when-to-use rules are given per branch: images take a note, a clip re-renders from its current plan, and changing clip content requires editing the plan first. It also states a prerequisite (get the human's go-ahead first) and where asset keys come from (review's structured result), leaving nothing to inference.

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