figma_insert_component_instance

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuine context beyond them: auto font loading when applying text overrides, the PNG screenshot return path via capture:true, and the AutoLayout insertion target. It stops short of stating what happens on duplicate insertion or undo semantics.

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?

Two front-loaded sentences with no filler: the first establishes the action and destination, the second enumerates the optional capabilities. Nothing redundant with the schema is repeated.

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 9-parameter, zero-required, nested-object tool with no output schema, the description covers the outcome (inserted instance) and notes the optional PNG return, which substitutes for missing return documentation. It omits multi-document targeting and placement fallback behavior, but those are covered in the schema.

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%, so all nine parameters including nested position/properties are documented in the schema, which sets the baseline at 3. The description adds only marginal meaning beyond that: it names variant selection and auto font loading for text_overrides, but does not clarify position/index behavior or scale semantics.

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+resource: create and insert an instance of a master component or component set into canvas or an AutoLayout container. This distinguishes it implicitly from figma_insert_svg (SVG content) and figma_find_components (discovery), though no sibling is named explicitly.

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?

Usage is only implied by the description ('insert an instance... into the canvas or target AutoLayout container'). It notes capture:true for visual verification but never says when to prefer this over figma_find_components for discovery or figma_insert_svg for raw assets, and gives no prerequisites or exclusions.

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