Query normalized Figma nodes

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true), so the bar is lower. The description adds 'without rendering' (a performance/behavior characteristic) and 'paginated evidence set' (output shape), which is genuine added value. It does not contradict the annotations. But it stops there — no mention of cursor mechanics or what an evidence set contains.

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?

A single sentence with zero waste and the core action front-loaded — structurally clean. But for a tool of this complexity it reads as under-specification rather than conciseness; one sentence cannot carry the semantics of a recursive selector schema and a required snapshot context.

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?

Complexity is high and schema coverage is 0%, yet the description leaves critical gaps: it never defines a snapshot or how to obtain one despite snapshot_id being the only required parameter, never clarifies order modes, and never distinguishes query_nodes from inspect_figma_file/analyze_figma_layout. The output schema and annotations help, but the required-parameter and selection-semantics gaps are too large.

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 0% on a deeply complex schema — a recursive all/any/not selector, roughly twenty filter fields, and an order object with six modes. The description adds only 'declarative logical selectors,' leaving the required snapshot_id, the order modes, cursor/page_size pagination, and cryptic filters (hierarchyPath, dimensionsSimilarToPeers, blockIndex, siblingIndex) entirely unexplained. With 0% coverage the description was required to compensate and barely does.

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 names a specific verb-resource pair — 'Applies declarative logical selectors... returns a paginated evidence set' over 'normalized Figma nodes' (from the title). This makes the read/query nature clear. However, it does not differentiate from siblings that also touch the Figma structure, notably inspect_figma_file and analyze_figma_layout, so the agent must infer where query_nodes sits among them.

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?

No when/when-not guidance is provided. The description never explains that snapshot_id is required or where a snapshot comes from, nor does it route the agent to an alternative (e.g., use analyze_figma_layout for layout analysis, inspect_figma_file for file structure). The 'without rendering' clause is the only implicit usage context and is too weak to count as guidance.

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