Set slide transitions

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

Adds substantial behavior beyond the annotations: partial-update semantics ('Fields left out keep each slide's current value'), a pre-flight read with refusal if the build lacks transitions ('nothing changed'), the validation rule that on-click plus delay is refused and coerced to 0, and the return value ('each slide's transition as read back'). Annotations (idempotent, non-destructive, not open-world) already cover safety, so a 4 is warranted rather than 5 – nothing about permissions or partial-failure behavior across 500 slides is stated.

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?

A single dense paragraph that front-loads the action and the enumerable fields, then behavioral caveats, then sibling disambiguation. Every clause carries information, though the packed list of field constraints makes it read more like a spec than a blurb; slightly tight trimming would still be possible.

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 an 8-parameter mutation tool with no output schema, the description covers mutation semantics, partial updates, refusal/rollback cases, cross-parameter validation, editor scope, and the return value. There is no meaningful gap an agent would need to fill before invoking it.

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 already 88% (baseline 3), but the description adds cross-parameter semantics the schema cannot express: duration's 0.01–10 s range, delay's 0–30 s range, that delay only applies with after-delay, and that a delay combined with on-click is refused. That interaction rule is genuine added meaning.

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 and resource ('Set the transition into each of these Figma Slides slides') and immediately lists the controllable fields (style, duration, curve, timing). It then explicitly rules out the two closest siblings, figma_set_reactions and figma_set_keyframes, so the agent can separate this from other motion/prototype tools without opening a 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?

Explicitly names the alternatives it is NOT for ('Not prototype interactions (figma_set_reactions) or layer animation (figma_set_keyframes)') and constrains eligibility ('Editors: Slides only, unverified'), which is exactly the when/when-not guidance needed given ~100 sibling tools.

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