Get motion (keyframe animation)

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds meaningful context: returning keyframe strings that match figma_set_keyframes, the 'temporary id' warning for layers inside animated frames, limits on what the Plugin API cannot report (loop mode, pivot), the beta/UNSUPPORTED behavior, and 'Design only.' These are beyond what annotations provide and materially aid correct use.

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?

Information-dense but front-loaded with the core purpose first. However, it packs multiple unrelated points (id semantics, defaults, limits, beta status, editor restriction) into a single unbroken block, making it dense and harder to scan than a structured list.

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, no-output-schema tool with 5 params and complex return sub-structures (timelineCohorts, motionPlans), the description covers what it returns, how it targets nodes, id caveats, and environmental constraints. It omits detail on coordinate/units for keyframe values and animation styles, leaving minor gaps.

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 already documents each parameter including defaults. The description adds indirect semantics (address layers by ids your create calls returned; a timeline id is never a node id) but does not clearly map to specific parameters like recursive or maxNodes, so it remains baseline.

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+resource ('The timeline animation of layers') and describes the exact return shape (keyframe tracks, animation styles, timelineCohorts, motionPlans). It explicitly distinguishes itself from the sibling figma_get_reactions ('This is Motion, not prototype interactions — those are figma_get_reactions'), so an agent can route without opening schemas.

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 strong routing context: 'This is Motion, not prototype interactions — those are figma_get_reactions', and explains default targeting (selection, then page, reads descendants). It also adds a prerequisite lift note: 'a screen never animates itself, its layers do.' It lacks explicit when-not-to-use framing beyond the reactions contrast, but the context is clear.

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