Skip to main content
Glama
Figma Local Bridge

Figma Local Bridge

by Miart

figma_swap_component

Swap one or more Figma instances to a different main component in one transaction, preserving compatible overrides and previewing losses via dry-run before applying.

Instructions

Swap one or more INSTANCEs to another main component in ONE transaction, preserving the overrides that still fit. The dry run (default) compares the old and new structures and returns, per target: a fingerprint of the instance and the target component, an exact or name-remapped path for every direct layer override, mapped component properties (by display name and type), root-level instance overrides (custom name, resized geometry, opacity, fills/strokes/effects and style links, layout placement) and every named loss. Apply with the returned planId and expectedFingerprints; it refuses a document that moved, a lossy swap unless allowLoss:true, and a library component whose structure could not be checked unless allowUnverified:true. Variant properties are not replayed — the chosen target component decides them. A layer whose node type changed, a missing layer, a changed nested component and a SLOT property are reported, never applied to a guessed layer. A target nested inside another INSTANCE is refused: that is an override of the outer instance, not an independent swap. The apply is one undo step; a failure rolls the whole call back, and the report says what rolled back. Plugin API swapComponent is the mechanism; Figma's own override heuristics are re-checked, not trusted.

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": {
      "nodeIds": "<nodeIds>"
    },
    "name": "figma_swap_component"
  }
}

Input Schema

NameRequiredDescriptionDefault
dryRunNoTRUE (default): compare and fingerprint only. FALSE: apply in one undo transaction.
planIdNoThe planId returned by figma_swap_component; 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.
nodeIdsYesINSTANCE targets (1–50). Their current main components may differ.
allowLossNoApply even when the dry run named a layer/property loss; the same losses are then reported
componentIdNoA local COMPONENT to swap to
componentKeyNoA local or library COMPONENT key; a library key is imported on apply
preserveSizeNoKeep an instance that was manually resized at its old size; false adopts the new component's size
componentNameNoExact local COMPONENT or COMPONENT_SET name; ambiguous names are refused
componentSetIdNoA local COMPONENT_SET; combine with variantProperties to pick a variant
allowUnverifiedNoApply a library component whose structure could not be compared before import
componentSetKeyNoA local or library COMPONENT_SET key; combine with variantProperties to pick a variant
variantPropertiesNoVariant selector for a component set, e.g. {"Size":"L","Tone":"Dark"}. Omit for the default variant.
expectedFingerprintsNoRequired on apply: nodeId -> fingerprint from the dry run, covering the instance state and target component. A changed target is refused before writing.
preserveRootOverridesNoReapply custom name, size, opacity, paints, effects, layout placement and style links that differ from the old main component

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.36.0

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so thoroughly: default dry-run mode, a single undo step, full rollback on failure, refusal of stale fingerprints, and explicit non-behaviors (variant properties not replayed, changed/missing layers and SLOT properties reported rather than guessed, nested-instance targets refused). It also discloses the mechanism (plugin API swapComponent) and that Figma's override heuristics are re-verified.

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 purpose is front-loaded in the opening clause and every following sentence adds a distinct constraint rather than restating the name. It is a dense single block of long sentences, which makes it slightly harder to scan, but no sentence is filler.

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 mutation tool with no annotations and no output schema, the description covers the two-phase workflow, the gate conditions, the failure and rollback behavior, and even enumerates what the per-target report contains. An agent has enough information to invoke dry run, interpret the plan, and apply safely.

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 coverage is 100%, so the schema baseline already documents all 15 parameters. The description still adds cross-parameter meaning the schema cannot convey: planId plus expectedFingerprints must come from the same dry run and are validated before writing, and allowLoss/allowUnverified gate specific refusal classes. Most of the remaining flags are left to their schema text.

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

Purpose4/5

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

States a specific verb and resource ('Swap one or more INSTANCEs to another main component in ONE transaction') and adds the scope constraint about preserving overrides. It does not explicitly distinguish itself from the similarly-purposed sibling figma_replace_repeated_with_component, so an agent must infer the boundary from the names alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Gives a clear workflow: dry run is the default, apply requires the returned planId and expectedFingerprints, and the refusal conditions (document moved, lossy swap without allowLoss, unverified library component without allowUnverified) are spelled out. It also states the case not to use it (target nested inside another INSTANCE). It stops short of naming when to pick a sibling tool instead.

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