figma_design

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

With no annotations provided, the description carries full disclosure burden. It reveals rejection of unknown/misspelled fields (no silent failures) and the dryRun:true option for validation without mutation. It implies design creation/sync is a write operation. Missing: no mention of authentication, idempotency, response behavior, or whether it overwrites existing designs. Still, the dry-run detail and strict validation policy provide good transparency.

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 with no filler. The first sentence states primary purpose, the second adds key differentiators, and the third covers validation/rejection behavior. Information is front-loaded and every sentence serves a distinct role.

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?

Given no output schema, the description omits return value/response format. It also doesn't explain whether the tool syncs to an existing design or always creates new, nor does it mention async behavior. However, the external documentation references and dry-run option provide enough completeness for a design creation tool with 2 parameters.

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 50% (doc has vague description, dryRun has none). The description adds meaning: dryRun's behavior ('validate + compile without touching Figma') and doc's constraints ('strict JSON', 'overlapping/absolute-positioned nodes', 'local image assets'). It compensates for the schema's gaps but still relies on external documentation for full understanding of the doc structure.

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 clearly states the verb (Build or sync), resource (design into Figma), and input format (strict JSON design document). It distinguishes itself from sibling tools by specifying unique capabilities (overlapping nodes, local assets) not offered by others, and references external documentation for schema details.

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 provides clear context for use (creating/syncing designs from JSON) and highlights key differentiators (overlapping nodes, local assets) vs. a non-sibling tool (Plumb). However, it does not explicitly state when NOT to use it among the listed sibling tools (e.g., 'use figma_delete_node instead for node deletion'). The reference to external gap analysis aids decision-making but lacks direct sibling comparisons.

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