Edit a managed After Effects project copy

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

Annotations only declare destructiveHint=true, so the description carries most of the burden and delivers: idempotency via UUID requestId ('prevents repeat execution after a retry or timeout') and the exact side-effect pipeline (captures pre-edit values, saves a checkpoint, edits, reads back, saves the project). Missing only auth/permission requirements and what the checkpoint can be rolled back to, which keeps it off a 5.

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?

Four sentences, each carrying distinct payload: capability, idempotency, execution pipeline, and status/scope exclusion. The operation and its limits are front-loaded before the recovery path and the negative scope statement.

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, no-output-schema mutation tool, the description covers atomicity, retry safety, checkpointing, and where to fetch a delayed result, plus the instance-addressing parameter is documented in the schema. It omits failure/error semantics and whether the checkpoint is restorable, which is the main remaining gap.

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?

Top-level schema description coverage is 100% and the nested operation enum is self-documenting, so the baseline is 3. The description still adds genuine meaning the schema does not: the requestId is framed as a deduplication/retry-safety key rather than just a uuid format, and it confirms the 12-edit ceiling as a hard constraint.

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 ('apply') and resource ('up to 12 typed, registered edits to the active managed .aep copy') with a clear scope limit. It also explicitly separates itself from sibling rendering tools with 'This does not render frames,' so an agent can distinguish it from ae_render_frame without opening any 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?

Gives a concrete follow-up path ('Use action=status with the same requestId to inspect a delayed receipt') and an explicit exclusion ('This does not render frames'). It stops short of routing the agent between this tool and the semantically adjacent ae_do / ae_workflow, so the when-to-use-vs-alternative coverage is clear but not exhaustive.

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