figma_metadata

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond the schema: it is a 'structural dump,' it is 'cheap' (implying low cost/performance), it has a default depth of 6 and node cap of 400 (though those are in the schema), and it explains what styles:true and css:true expand the output to include. It doesn't mention pagination or truncation behavior, but the maxNodes parameter covers the cap.

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

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

Three sentences, each earning its place. The first sentence defines the core output and the key usage pattern (omit nodeId). The second sentence explains the styles flag with a comprehensive list. The third sentence explains the css flag. No filler, no repetition of schema details that don't need emphasis.

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

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

For a read-only inspection tool with 100% schema coverage and no output schema, the description is quite complete. It covers what the tool returns, how to scope it (nodeId), and how to enrich output (styles, css). The only minor gap is that it doesn't explicitly describe the output structure or warn about the maxNodes cap truncation, but the schema covers maxNodes and the description's 'structural dump' phrasing implies a JSON tree.

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

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 adds meaning beyond the schema by explaining the purpose of the styles flag ('fills, strokes, effects, opacity, corner radius, auto-layout and text styles per node — plus bound variables, named styles, and for instances the main component and its property values') and the css flag ('the design-to-code handoff'). It also clarifies nodeId semantics ('Omit for the current page'), which the schema already states but the description reinforces in context.

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

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

The description opens with a precise verb and resource: 'Structural dump of a node subtree' and enumerates exactly what is returned (id, name, type, x/y/w/h, text characters). It also distinguishes itself from editing tools by calling itself a 'cheap way to find node IDs before editing,' which separates it from siblings like figma_find and figma_export.

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

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

The description explicitly states when to use it: 'Cheap way to find node IDs before editing.' It also gives concrete usage guidance for optional flags: 'Pass styles:true to also get...' and 'css:true adds the CSS Figma computes per node.' This tells an agent exactly how to invoke it for different needs and implies it is the read-only exploration tool among siblings.

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