Place a component

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

Annotations already mark this as a mutating, destructive-hinted operation. The description adds useful behavior beyond that: placing an instance keeps the link to the component, and naming a variant set results in its default variant. This gives agents expectations about side effects and variant handling that the annotations alone do not convey.

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?

Four short sentences, each earning its place: core action, required id source, variant nuance, and rationale for preferring the tool. The purpose is front-loaded and there is no filler or repetition of schema details.

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 creation tool with no output schema, the description does not mention return value or resulting node id, which an agent would likely need for follow-up operations like setting properties. It covers purpose, id source, and variant behavior, but omits what the caller gets back and where the instance is placed when parentId is not provided.

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 only 20%, so the description must compensate. It does help by explaining that componentId comes from figma_list_library and by adding variant-set behavior for name. However, x, y, and parentId receive no semantic explanation, so several parameters are still underspecified.

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 specific verb and resource: 'Creates an instance of a component in this file.' It also differentiates itself from drawing a lookalike by emphasizing that an instance keeps its link to the component and updates with it, which clarifies what kind of creation this is versus sibling creation tools.

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?

It gives clear context: get the id from figma_list_library and prefer this tool over drawing a lookalike when you want the component link preserved. It does not explicitly name alternative sibling tools or state when not to use it, so it stops short of fully explicit exclusionary guidance.

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