Preview Motion Graphics Demo

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by enumerating what it does not do: 'never creates demo assets, imports files, creates a sequence, or changes Premiere.' This adds specific behavioral boundaries beyond the generic hints, plus the note that apply needs a confirmation token. No contradiction with annotations.

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?

Two sentences: the first fronts the core capability, the second packs all necessary exclusions and the apply-token caveat. No filler or redundant restating of the name/title.

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 read-only preview tool with full schema documentation, an output schema, and safety annotations, the description provides enough context: it identifies the workflow stage (preview vs apply), the side-effect boundary, and the source of assets. Minor gap: it doesn't explicitly spell out what 'preview' produces (e.g., whether it plays in a monitor or writes a temporary file), but the output schema likely covers the return structure, so this is not a critical omission.

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 100%, so the schema itself documents all 7 parameters including defaults and notes like 'existing project-item node IDs' and 'empty destination sequence.' The description adds only a high-level constraint ('from existing project items,' 'never imports files') that is already implied by the schema, so it adds minimal semantic value beyond the structured fields.

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 opens with 'Preview a contained motion-graphics demo assembly from existing project items,' giving a specific verb, resource, and scope. It distinguishes itself from sibling preview/apply tools by explicitly stating it 'never creates demo assets, imports files, creates a sequence, or changes Premiere' and mentions the apply confirmation token. This makes the tool's purpose unmistakable.

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?

The description clearly frames this as a no-side-effect preview path and notes that 'apply requires an exact confirmation token,' signaling that a separate apply step is needed to commit changes. However, it doesn't explicitly name alternative preview siblings (e.g., preview_product_spot) or list conditions such as 'use when reviewing a motion graphics demo without mutating the project,' so guidance 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.