Set the motion plan of a frame

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

Goes well beyond the annotations: 'Checked before anything is stored, every problem listed at once' discloses the validation model and error-reporting shape, including the concrete rules (grid alignment, no gaps/overlaps, max(5/6 s, 0.3 s/word) read time, accents on the beat grid). It also discloses persistence semantics ('stored on the frame in shared plugin data, so every session sees it; a new call replaces it'), which explains the idempotentHint, and the Design-only editor restriction.

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 purpose and packed with load-bearing content — validation rules, storage, downstream consumers — with little filler. However it is delivered as one dense semicolon-chained block, which hurts scannability for a 10-parameter tool; bulleted grouping of validation rules would read better at the same length.

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 complex write tool with nested brief/beats/accept objects and no output schema, the description covers what is validated, when errors surface (all at once), where the plan is persisted, who can see it, and which tools read it. There is no output schema, yet the description still conveys the effective response behavior, so nothing an agent needs to call this 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 rules the schema does not encode: the reading-time heuristic for onScreen copy, '[picture notes] untimed', and the linkage of holds/brandId/ctaId/accept to specific figma_check_motion outputs. These clarify how values are actually consumed downstream rather than restating field names.

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?

Opens with a specific verb+resource+scope: 'Record the plan of one animated top-level frame before animating it.' It also positions itself against the siblings it interacts with (figma_get_motion_context returns it, figma_check_motion judges against it), so an agent can place it in the motion workflow 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?

States the ordering condition ('before animating it') and the hard dependency: under BRIDGE_PROCESS=strict (default) figma_set_keyframes and figma_remove_keyframes refuse a frame without a plan. It also names the editors allowed ('Design only') and tells the caller which sibling returns or consumes the stored plan. This is explicit when/when-not guidance.

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