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

Annotations already flag destructive=true and idempotent=true, but the description adds real operational context beyond them: the call saves a playable project, unsupported edits are refused without rebuilding, operation_id must be preserved on retries, and it consumes the account's direct-edit allowance at no credit cost. This is the kind of failure/retry/billing behavior an agent cannot infer from structured fields alone.

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?

Roughly five short sentences, front-loaded with the core action and its key semantic distinction, then prerequisites and cost. Some clauses are telegraphic ("Cost: Free: no credits.", "Unsupported changes refuse without rebuilding."), which costs a little readability but no sentence is filler.

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 destructive 6-param edit tool, it covers the prerequisite read, the identity of the asset reference, retry/idempotency behavior, refusal semantics, and how to obtain the resulting file (with a pointer to check_video). With an output schema present, no return-value explanation is required, so nothing material 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; the description goes further by explaining that asset_id is a version-scoped picture key rather than a library ID, and that base_version/output_id should come from get_project_context. It doesn't cover scene_id or video_id sourcing, so it stops short of a 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?

"Replace the selected scene picture with a picture key already used in this version" names a specific verb, resource, and scope, and immediately disambiguates from library-asset operations (import_asset/list_assets) and from the sibling replace_scene_screen. An agent can tell exactly what changes and what the input refers to without opening the schema.

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?

It gives an explicit prerequisite workflow ("Read get_project_context first and pass its base_version and selected output_id"), names an exclusion (not a library asset ID), and routes a related need to a different tool ("request a file separately with check_video with_download"). Conditions for choosing alternatives are stated rather than implied.

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