figma_set_layout

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

With no annotations present, the description carries the full behavioral burden and does meaningful work: 'Only the fields you pass change' discloses partial-update semantics for a 17-parameter setter, 'Returns the resulting layout, with grid tracks as CSS' discloses the response shape, and 'Requires Desktop Bridge' discloses an environment prerequisite. It stops short of saying what happens to children not listed or whether re-parenting nodes into the frame is destructive, which is the main residual gap.

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 front-loaded paragraph that begins with purpose and then walks the parameter space in the order an agent would set it. It is dense rather than bloated, though re-listing the enum members (MIN, CENTER, MAX, SPACE_BETWEEN, …) duplicates what the schema already declares and could be trimmed.

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 17-parameter nested-object tool with no output schema and no annotations, the description covers the mode split, the parameter surface, partial-update behavior, return format, and the Desktop Bridge requirement. Missing pieces are secondary: the meaning of width/height, how the children array's ordering interacts with autoFlow, and error/rejection behavior in Cloud Mode.

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 only 47%, so the description must compensate, and it largely does: it names the auto-layout knobs (gap, padding, primaryAlign, counterAlign, wrap/counterAxisGap/alignContent, sizing), spells out the grid track string grammar with concrete examples ('repeat(3, 1fr)', 'auto 1fr', or a count), and covers per-child row, column, spans and alignment. width/height and reverseZIndex are left unexplained in both places, keeping it below 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?

Opens with a specific verb and resource: 'Set a frame's auto layout or grid layout in one call, and place its children.' That scope is distinct from the neighboring node-mutation tools (figma_resize_node, figma_move_node, figma_arrange_component_set), and the two-mode breakdown (auto layout vs grid) makes the capability unambiguous.

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?

Usage context is implied by the field enumerations and by 'Requires Desktop Bridge,' and 'in one call' hints at batching layout plus child placement instead of multiple calls. But it never states when to use this versus figma_resize_node or figma_arrange_component_set, and offers no exclusions or prerequisites beyond the Desktop Bridge note.

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