Skip to main content
Glama

Get metadata

figma_local_get_metadata
Read-only

Returns XML metadata for a Figma node or page—IDs, layer types, names, positions, and sizes—for a structural overview before requesting fuller design context.

Instructions

IMPORTANT: Always prefer figma_local_get_design_context. Get metadata for a node or page in XML format: node IDs, layer types, names, positions and sizes only. Useful for an overview of the structure; call figma_local_get_design_context on the node IDs it contains. The nodeId can also be a page id (e.g. 0:1). When nodeId is omitted, returns the top-level pages of the document instead. If the URL includes node-id, pass it as nodeId; otherwise omit nodeId. For branch URLs use the branchKey as the fileKey.

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": {
      "fileKey": "<fileKey>"
    },
    "name": "figma_local_get_metadata"
  }
}

Input Schema

NameRequiredDescriptionDefault
nodeIdNoThe ID of the node in the Figma document, eg. "123:456" or "123-456". Extract it from the URL's node-id query parameter. Do not pass an empty or guessed nodeId.
fileKeyYesThe key of the Figma file to use. If a URL is provided, extract the file key from it: for https://figma.com/design/:fileKey/:fileName?node-id=1-2 the fileKey is `:fileKey`. For https://figma.com/design/:fileKey/branch/:branchKey/:fileName use the branchKey. A full URL is also accepted.
clientLanguagesNoA comma separated list of programming languages used by the client in the current context, e.g. `javascript`, `html,css,typescript`. If you do not know, list `unknown`.
clientFrameworksNoA comma separated list of frameworks used by the client in the current context, e.g. `react`, `vue`, `django`. If you do not know, list `unknown`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description goes further by disclosing the XML output format, the exact fields returned and explicitly excluded, and the default behavior when nodeId is omitted (top-level pages). It does not mention pagination or size limits, which is the only remaining behavioral gap.

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 routing warning is front-loaded and each sentence carries an operative rule; there is no filler. The branchKey instruction duplicates the fileKey schema text, a minor redundancy that keeps it just short of top marks.

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 compensates by describing the return format and contents, plus the default no-nodeId behavior. Combined with the schema documenting the client-hint parameters, an agent has everything needed to call this correctly; only edge cases like very large documents are unaddressed.

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 still adds meaning by noting nodeId may be a page id (e.g. 0:1), by specifying omit-versus-pass logic tied to the presence of node-id in the URL, and by restating the branchKey rule for branch URLs. Only clientLanguages/clientFrameworks are left to the schema, which handles them adequately.

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 ("Get metadata for a node or page") and immediately bounds the payload: "node IDs, layer types, names, positions and sizes only." It also differentiates itself from the closest sibling by telling the agent to prefer figma_local_get_design_context, so the tool's role is unmistakable.

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?

Gives an explicit preference rule ("Always prefer figma_local_get_design_context"), a positive use case ("overview of the structure"), a follow-up path (call the sibling on the node IDs returned), and conditional routing for nodeId and branch URLs. The when/when-not decision is fully spelled out.

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