plumb_describe

Text-only visual description of a Figma screen — a per-region narrative plus a flat child summary, derived from the PDS. For harnesses that can't read screenshots, sandboxed read environments, or token-conscious flows that don't want a full structural spec.

Inputs

Field	Type	Notes
id	string · optional	Node id to describe.
name	string · optional	Screen name (plugin path).
fileKey	string · optional	File key (REST path).
url	string · optional	Paste a Figma URL — fileKey and id auto-extracted.
depth	number · optional	Levels of the tree to mine for the narrative. 1–6. Default 2.

Returns

{
  "source": "plugin",
  "screen": "Settings → Profile",
  "regions": {
    "top-left":     "A 96×96 avatar circle next to a 24px heading 'Profile'.",
    "top-right":    "A ghost 'Cancel' button and a primary 'Save' button.",
    "center":       "Two stacked input fields — 'Name' and 'Email'.",
    "bottom-right": "A small grey caption: 'Last updated 3 days ago.'"
  },
  "children": [
    { "name": "Avatar",   "type": "frame",    "box": { "w": 96,  "h": 96 } },
    { "name": "Heading",  "type": "text",     "chars": "Profile" },
    { "name": "Save",     "type": "instance", "component": "btn/primary" }
    // …
  ]
}

When the agent should use it

• The agent's harness can't read the plumb_screenshot PNG (image-blind tool calls, sandboxed file reads).
• It needs a quick "what's on this screen?" answer without the full PDS.
• Pair with plumb_node for structure + plumb_describe for prose, or with plumb_screenshot when both are available.

Notes

Both paths supported (plugin and REST). REST path is cached per fileKey:id:depth.

The narrative is deterministic — it's mined from the PDS, not generated by a model. Same input → same description.