Create variables

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

Annotations cover readOnly=false, idempotent=true and destructive=false, but the description adds substantially more: atomic validation ('Everything is checked before the first variable exists, so a refusal creates nothing'), the 200-per-call cap with pacing, alias ordering/type constraints, and editor availability (Design verified; FigJam/Slides unverified). No contradiction with the idempotency annotation.

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 the core operation and then proceeds through values, atomicity, ifExists, limits, sibling routing and editor support in one dense but waste-free passage. Every sentence carries information an agent needs; nothing is padding.

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?

Covers atomicity, failure semantics, ordering constraints, rate/limit behavior and idempotency-key retry semantics, which is thorough for a 5-param mutation with no output schema. The only real gap is that it never says what a successful call returns (e.g. created variable ids) that follow-up alias or bind calls would need.

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 already 80%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: alias targets must exist already or appear EARLIER in the same call with the same type, and ifExists governs what an existing name does. Value string formats largely restate the schema, hence not a 5.

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 with scope: 'A token set in ONE call (one undo step)' that creates primitives then aliasing semantic tokens. It explicitly distinguishes itself from the sibling figma_create_variable ('For one variable figma_create_variable is enough'), so an agent can route correctly without opening either 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?

Names the alternatives and the conditions selecting them: use figma_create_variable for a single variable, figma_set_variable_properties to change properties later. It also spells out the ifExists decision (error/skip/update) and the ordering rule for aliases, which is exactly the guidance needed before calling.

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