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

Goes well beyond the annotations: free instant spec-version bump, a re-render quote priced on edited length, and a hard stop requiring confirm_operation for voice-over edits. The versioning model implied by base_spec_version is gestured at ('a new spec version') but not fully explained, and nothing is said about what a stale base_spec_version does or why idempotentHint=false matters.

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 core action and sibling anchor, then the three behavioral branches. Dense but nearly every clause carries information; the parenthetical field lists and stacked exceptions make it read as a wall of text rather than scannable statements.

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, the description usefully describes what comes back (a new spec version plus a re-render quote, or a quote_id). For a mutation tool with three required params at 0% schema coverage, the main remaining hole is base_spec_version semantics and the failure mode for a stale version.

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 must compensate. It helps greatly on 'ops' by pointing to update_storyboard's op vocabulary, and it implies video_id must refer to a previously rendered video. But base_spec_version — a required integer with a min of 1 and the key to optimistic concurrency — is never explained, leaving one of three parameters semantically opaque.

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 verb+resource ('Edits a rendered video') and immediately anchors it to the sibling it mirrors ('the same ops as update_storyboard'), so an agent can tell edit_video apart from update_storyboard without opening either schema. The closing precondition ('Only for a video that was rendered at least once') further narrows the target resource.

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?

Explicitly partitions when edits apply immediately (text, order, timing, CTA, captions) versus when they are not applied and instead yield a quote_id to feed confirm_operation (voice-over changes). It also states an exclusion ('New generated images aren't available: media must come from the project') and names the downstream tool for the deferred path.

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