figma_analyze_component_set

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

No annotations are present, so the description carries the full burden; it does disclose the environment prerequisite and enumerates in detail what the operation produces, which is the behavior an agent most needs here. It does not explicitly state that the call is read-only/non-mutating or whether it is expensive on large sets, which leaves a small gap for an unannotated tool.

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?

Purpose and node scoping are front-loaded, but the return-value enumeration becomes a dense run-on with deeply nested parentheses and backticked property names, making it hard to scan. Because there is no output schema the detail is earned, yet it could be restructured into a short list instead of one sprawling sentence.

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?

With no output schema and no annotations, the description supplies exactly what would otherwise be missing: the shape of the response across five numbered categories, the node-type constraint, and the plugin prerequisite. An agent can decide whether to call it and predict the payload without further information.

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 coverage is 100% with a single required nodeId already documented as a COMPONENT_SET node ID, so the schema does the heavy lifting. The description reinforces the constraint that it must be the parent node rather than a variant, which adds a real usage guard beyond the schema text.

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?

States a specific verb and resource — analyze a Figma COMPONENT_SET to extract a variant state machine, cross-variant diffs, property mappings and slots for code generation — which is a distinctive, non-tautological purpose. The scope is clear enough that an agent knows what comes back, but it never distinguishes itself from plausible siblings doing adjacent work (figma_get_component_details, figma_ds_extract_component, figma_get_component_for_development_deep).

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?

Gives an explicit when-not: 'Use this on the parent COMPONENT_SET node, not individual variants,' plus a hard prerequisite ('Requires Desktop Bridge plugin'). It does not name any alternative tool to use when the node is not a COMPONENT_SET, so the routing guidance is clear but not complete.

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