set_frame_properties

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

With no annotations, the description carries the full behavioral burden and does well: it discloses operation ordering (x/y applied last), the flow effect of ABSOLUTE/AUTO on the parent, and the stacking meaning of itemReverseZIndex. It does not mention permissions, error behavior, or side effects on sibling nodes, which keeps it below 5 for a mutation tool.

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, front-loaded sentence that leads with the tool's scope and then unpacks each property; no filler. The stacked parentheticals make it slightly heavy to parse, which keeps it just below top marks.

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 6-parameter mutation tool with no annotations and no output schema, the description covers the non-obvious parameters and their interactions well. It omits return/error behavior, but the absence of an output schema and the low stakes of a Figma property setter make that a minor gap.

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 real meaning beyond the schema: it explains that ABSOLUTE removes a child from its auto-layout parent's flow, that itemReverseZIndex puts the first child on top, and that x/y are applied after positioning. This is value-add over the terse schema descriptions.

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 ('Set') and resource ('frame layout properties') and immediately carves out its niche with 'not covered by other tools,' then enumerates the exact properties (layoutPositioning, itemReverseZIndex, clipsContent, x/y). An agent can distinguish it from siblings like set_layout_mode, set_padding, and set_item_spacing without opening the 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?

The 'not covered by other tools' framing plus the explanation of ABSOLUTE/AUTO semantics gives clear context for when each property applies, and the note that 'x/y are applied last, so an ABSOLUTE child can be positioned in the same call' is genuine usage guidance. It stops short of naming specific alternative tools or explicit when-not-to-use conditions, so it falls short of a 5.

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