Skip to main content
Glama

nodes

Reads detailed Figma layer data—fills, strokes, text, auto-layout, masks, components—from saved .fig files when compact summaries lack detail; writes large JSON to a file to avoid reply limits.

Instructions

A node or exact instance sublayer as the per-node object of a Figma REST nodes response ({document, components, componentSets, styles, schemaVersion, _figlens}; _figlens.semantics.verification covers every node's _figlens.semantics): instances expanded, fills, strokes, effects, full text, auto-layout, masks, component data, Dev Mode annotations with labelMarkdown (named annotationCategories at the top level) and devStatus. Use it when inspect's compact summary lacks paints, masks or full text. A whole screen is often hundreds of KB, and agent hosts may show only part of a reply over about 20 KB, so read a screen with out, then query that file with jq or read it in parts; or scope to a smaller node, use inspect (flat for an outline), or write a bundle. Without out, replies over the MCP reply budget fail with response_budget_exceeded; with out, only a selection that outgrows that budget while being built does. Opt-in compact shares styles, and subtrees additionally shares templates; resolve the versioned references before passing to REST consumers. The reply budget applies to the compact result, with separate finite construction limits.

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": {
      "file": "<file>",
      "node": "<node>"
    },
    "name": "nodes"
  }
}

Input Schema

NameRequiredDescriptionDefault
outNowrite the JSON (the same text the reply would carry) to this .json file (other extensions are refused) and reply {path, bytes, lines} instead. Unless the user names one, use .figlens/exports/ under the project root, created with a .gitignore containing * so it stays out of Git; create the parent directory first; never overwrites the source design
fileYesthe saved .fig: a local path (absolute recommended), or gs://bucket/object using gcloud; remote sources are unavailable with --root
nodeYesa stored node id (12:345 or 12-345), full instance sublayer id (I12:345;67:89) from inspect/nodes, or a Figma URL with ?node-id=
compactNolossless figlens.nodes.compact.v1 wrapper: data contains node style slots as {$style: index}, sharedStyles holds their literal values; default false; use for large full-paint reads, not REST consumers
subtreesNowith compact: true, also share repeated subtrees; {$subtree: index, placements: [...]} references subtrees templates with preorder id/absoluteBoundingBox/absoluteRenderBounds overrides; default false

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.14.1
    • addedInput schema / properties / out
      Added value: +{
      +  "description": "write the JSON (the same text the reply would carry) to this .json file (other extensions are refused) and reply {path, bytes, lines} instead. Unless the user names one, use .figlens/exports/ under the project root, created with a .gitignore containing * so it stays out of Git; create the parent directory first; never overwrites the source design",
      +  "minLength": 1,
      +  "type": "string"
      +}
  2. Changed2 schema fields changedv0.13.1
    • addedInput schema / properties / compact
      Added value: +{
      +  "default": false,
      +  "description": "lossless figlens.nodes.compact.v1 wrapper: data contains node style slots as {$style: index}, sharedStyles holds their literal values; default false; use for large full-paint reads, not REST consumers",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / subtrees
      Added value: +{
      +  "default": false,
      +  "description": "with compact: true, also share repeated subtrees; {$subtree: index, placements: [...]} references subtrees templates with preorder id/absoluteBoundingBox/absoluteRenderBounds overrides; default false",
      +  "type": "boolean"
      +}
  3. Changed1 schema field changedv0.9.3
    • changedInput schema / additionalProperties
      Previous value: -trueNew value: +false
  4. Changed4 schema fields changedv0.7.2
    • addedInput schema / additionalProperties
      Added value: +true
    • changedInput schema / properties / file / description
      Previous value: -"the .fig file (File > Save local copy): an absolute path, or gs://bucket/object"New value: +"the saved .fig: a local path (absolute recommended), or gs://bucket/object using gcloud; remote sources are unavailable with --root"
    • addedInput schema / properties / file / minLength
      Added value: +1
    • changedInput schema / properties / node / description
      Previous value: -"a node id (12:345 or 12-345) or a Figma URL with ?node-id="New value: +"a stored node id (12:345 or 12-345), full instance sublayer id (I12:345;67:89) from inspect/nodes, or a Figma URL with ?node-id="
  5. First observed

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does well. It discloses reply-budget failure modes (response_budget_exceeded without out versus only when an out selection outgrows the budget), that compact shares styles and subtrees shares templates, that versioned references must be resolved before REST consumption, and that out never overwrites the source design. These are exactly the operational details an agent needs before invoking a read tool that can write an export file.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

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

The content is dense and mostly earns its place, but it is delivered in long, run-on sentences that are hard to scan. The purpose is front-loaded, yet the middle sections bundle budget behavior, compact/subtrees sharing, and file-output rules into one block. Better sentence breaks or bullets would improve structure without removing substance.

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?

There is no output schema, so the description must explain what comes back, and it does: it names the top-level response fields and details the expanded node data. It also covers the major operational risk (reply budget) and the out-file alternative with path conventions. For a complex read/export tool with no annotations and no output schema, this is complete enough to call correctly.

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 parameter descriptions already carry most semantics. The main description still adds value beyond the schema by explaining compact's intended use ('for large full-paint reads, not REST consumers') and subtrees' sharing of templates via versioned references. That is more than a baseline repetition of schema text, though not a full elaboration of every parameter.

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?

The description identifies the resource (a node or exact instance sublayer) and the response shape (Figma REST nodes object with document, components, etc.). It distinguishes itself from inspect by saying to use it when inspect's compact summary lacks paints, masks, or full text. However, the opening is a noun phrase rather than a clear verb like 'fetch' or 'read', so the action is implied rather than stated explicitly.

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 guidance: use when inspect's compact summary lacks paints, masks, or full text. It also names alternatives and conditions: scope to a smaller node, use inspect for a flat outline, use out for large reads, or write a bundle. This is a strong example of routing an agent among sibling tools.

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