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

The description discloses behavior well beyond the annotations: null layout restores the authored layout, authored animation is preserved, unsupported changes refuse without rebuilding, retries must preserve operation_id and exact inputs, and a direct-edit allowance/cost applies. These details add substantial operational context for a destructive but idempotent 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 description is front-loaded and dense with useful constraints, and most sentences carry operational value. It is slightly list-like and could be structured more cleanly, but it avoids repetition and wasted prose.

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, idempotent mutation with an output schema, the description covers prerequisites, preservation behavior, refusal behavior, retry guidance, file-download separation, and cost. Nothing essential for correct invocation appears 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 67%, and the description adds meaning for key parameters: layout null semantics, base_version/output_id context from get_project_context, and operation_id retry behavior. It does not fully explain the element identifier or layout unit semantics, but it compensates for much of the schema gap.

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 description states a specific action set (move, scale, rotate), the exact resource (one returned editable canvas element), and the unit context. It clearly distinguishes layout operations from content or scene operations through its focus on element layout.

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 concrete prerequisites: read get_project_context first, pass base_version and selected output_id, and preserve operation_id on retries. It also routes file requests to check_video with_download, but it does not explicitly contrast when to use this versus sibling tools like set_element_content.

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