Skip to main content
Glama
Figma Local Bridge

Figma Local Bridge

by Miart

figma_variant_set

Build or update a Figma component set as a property matrix in one undoable transaction: combine components, add variants, or rename properties, with dry-run validation before writing.

Instructions

Author a COMPONENT_SET as a property matrix in ONE transaction. action "combine" turns standalone COMPONENTs into a new set (names are replaced by the requested variant names), "add" clones an existing variant with a new property combination, and "edit" renames one variant in place. The dry run (default) validates the whole matrix: every variant has the same property names, no combination is duplicated, the destination is not an INSTANCE, another set or a COMPONENT definition, and a combine destination is not inside one of its own variants. It returns per-component and per-set fingerprints plus the destination layout, so a changed document is refused before writing. Apply with the returned planId and expectedFingerprints; it is one undo transaction. After writing, component names are read back as variantProperties and the set matrix is verified — a Figma that did not accept the name is rolled back, not reported as a success; if the undo itself fails, the error says ROLLBACK FAILED. Components already in a set are refused by combine; components inside an INSTANCE are refused. A combine destination inside a COMPONENT is refused because Figma will not reparent a component into a component definition; add and edit still operate on an existing set.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "figma_variant_set"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNocombine: the new COMPONENT_SET name
indexNoadd: insertion index inside the set; omitted appends
actionYescombine: standalone COMPONENTs -> new COMPONENT_SET | add: clone a variant with new properties | edit: rename one variant's properties
dryRunNoTRUE (default): validate and fingerprint only. FALSE: apply in one undo transaction.
planIdNoThe planId returned by figma_variant_set; if supplied on apply, a different request is refused before it is sent
fileKeyNoWhich connected Figma file to use: its fileKey (figma_whoami) or, when omitted, the only connected file. Required once more than one file is connected; figma_ping lists them.
parentIdNocombine: where to create the set. Omit when all components already share a parent
sourceIdNoadd: the existing variant to clone
parentKeyNocombine: stable key of the destination, resolved on the current page
sourceKeyNoadd: stable key of the variant to clone, resolved on the current page
variantIdNoedit: the variant to rename
componentsNocombine: the components and the variant properties each one should represent
propertiesNoadd/edit: the new variant's complete property map
variantKeyNoedit: stable key of the variant to rename, resolved on the current page
expectedFingerprintsNoRequired on apply: nodeId -> fingerprint from the dry run, covering every component, the set and its destination layout.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.36.0

TDQS

A4.8/5.0
Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does: it discloses the dry-run default, the fingerprint/planId safety protocol, that apply is a single undo transaction, and that names are read back and rolled back rather than reported as success, including the distinct ROLLBACK FAILED error. The refusal rules and the reason for them (Figma will not reparent a component into a component definition) are unusually thorough 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is front-loaded with purpose and the three actions, then validation, then apply/rollback behavior, so structure is strong. It is dense and slightly repetitive around the refusal cases ("is refused" appears four times), which costs a bit of readability but every clause carries operational meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter, nested-object mutation tool with no annotations and no output schema, the description covers the parts structured data cannot: validation guarantees, the apply handshake, rollback semantics, and what the dry run returns (per-component and per-set fingerprints plus destination layout). Nothing an agent needs in order to invoke this safely appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description goes beyond it by explaining how planId and expectedFingerprints are used together on apply and by framing the components/properties input as a complete property matrix whose variants must share property names. It does not add much to individual id/key parameters, which the schema already documents well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("Author a COMPONENT_SET as a property matrix in ONE transaction") and then disambiguates its three modes: combine turns standalone COMPONENTs into a set, add clones a variant, edit renames one variant in place. An agent can tell exactly which operation each action value performs 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use per action plus concrete when-not conditions: components already in a set are refused by combine, components inside an INSTANCE are refused, and a combine destination inside a COMPONENT is refused while add/edit still work on an existing set — which effectively routes the agent to the fallback mode. The dry-run-first, then apply-with-planId workflow is stated as the required sequence.

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