Skip to main content
Glama
Sign In
Figxel

Figxel

by AvYour
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Add variable mode

figma_add_variable_mode
Idempotent

Add a mode (e.g. "Dark") to a variable collection; returns its modeId. Modes beyond the first need a paid plan — on a Starter file Figma refuses, and its message is returned. Then set values per mode with figma_set_variable_value.

Instructions

Add a mode (e.g. "Dark") to a variable collection; returns its modeId. Modes beyond the first need a paid plan — on a Starter file Figma refuses, and its message is returned. Then set values per mode with figma_set_variable_value. Editors: Design; unverified: FigJam, Slides.

Input Schema

NameRequiredDescriptionDefault
nameYes
forceNoOverwrite on purpose. A write to a node someone changed after you last read it is refused (STALE); read it again and resend instead. Pass true only when the person said to overwrite their edit.
sessionNoOptional sessionId or file name, to pick a Figma file when more than one is connected.
collectionIdYes
idempotencyKeyNoCaller-owned retry key, ≤128 chars. Re-calling with the same key never executes twice: it returns the existing result, or waits for the op still in flight. Supply your own for anything large — if the MCP client times out (rather than the bridge), only a key you chose can be used to retry safely.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.0
    • addedInput schema / properties / force
      Added value: +{
+  "description": "Overwrite on purpose. A write to a node someone changed after you last read it is refused (STALE); read it again and resend instead. Pass true only when the person said to overwrite their edit.",
+  "type": "boolean"
+}
  2. First observedv0.1.1

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses that the call returns a modeId, that Figma refuses extra modes on a Starter file and returns its own message, and that Design is verified while FigJam and Slides are unverified. The fail-mode and output-value context is exactly what a mutation tool needs on top of destructiveHint=false and idempotentHint=true.

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?

Three dense sentences with the core action and return value front-loaded, then the plan gating, then the follow-up tool and editor support. The telegraphic final clause ("Editors: Design; unverified: FigJam, Slides.") trades readability for brevity but still earns its place.

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

Completeness4/5

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

With no output schema, the description correctly states the return value, and it covers the paid-plan failure path for a 5-parameter mutation. Only the optional parameters' behavior (retry key, session disambiguation, overwrite semantics) is left entirely to the schema, which is acceptable given partial coverage.

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

Parameters3/5

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

The description maps collectionId ("to a variable collection") and name (the mode name, e.g. "Dark"), adding modest meaning, but says nothing about force, session, or idempotencyKey even though only 60% of parameters carry schema descriptions. The typed hints in the schema still cover those, so the description neither fully compensates nor needs to.

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?

States a specific verb and resource ("Add a mode ... to a variable collection") and names the return value (modeId), so the agent knows exactly what effect to expect. It is clearly distinguishable from adjacent tools like figma_create_variable_collection and figma_set_variable_value.

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 when: adding a mode to a collection, plus the sequencing hint to follow up with figma_set_variable_value per mode, and warns that non-first modes require a paid plan. It does not explicitly name alternatives for renaming/updating an existing mode (e.g. figma_set_variable_mode or figma_update_variable_collection), so routing is implied rather than stated.

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

Deploy Server

Other Tools