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

Annotations only declare readOnly/destructive/idempotent/openWorld flags; the description goes well beyond by disclosing that no media is sent, that media without a `path` opens offline needing relink, the quota/auth model (3/month per network, API key packs via Bearer header), and that unknown fields are hard errors. That is exactly the behavioral context annotations cannot carry.

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 outcome, then inputs, then return value, then constraints and auth - a sensible order. It is dense but long; the inline sample document is useful yet takes substantial space, keeping it just short of a 5.

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 two-parameter, no-output-schema tool, the description covers the return shape (zip embedded resource with per-editor folder and report.json, plus a text summary of warnings), the media-linking behavior, quota and auth, and links to the full spec. Nothing an agent needs to call it correctly is missing.

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 100%, so the baseline is 3, but the description adds real semantics: `edit` is an Edit JSON v1 document with times in seconds and positions as frame fractions, unknown fields error, and `targets` selects which editor project formats are produced. The 8 MB limit and enum values are left to the schema, which already documents them.

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 (turn an edit into) and resource (projects that open in CapCut, Premiere Pro, Resolve, Final Cut Pro), plus the editable-text captions outcome. This is clearly distinct from siblings like convert_file and inspect_file, which operate on files rather than producing multi-editor project bundles.

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?

Specifies the two required inputs (an Edit JSON document in `edit`, 1-4 editors in `targets`) and what each call consumes against the export allowance, which tells the agent to batch targets in one call. It doesn't explicitly say when to prefer convert_file over this tool, so it falls short of naming alternatives.

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