figma_delete_nodes

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description earns credit by adding recoverability ('Normal Figma Undo remains available') and a scoping constraint on when destruction is justified. It omits the practical limit that at most 200 nodes can be deleted per call and says nothing about effects on child nodes or connections.

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 short sentences, zero filler, with the core action stated first and the scoping caveat immediately after. The recoverability note is one clause and earns its place.

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 two-parameter destructive tool with no output schema, the description covers what is destroyed, when destruction is warranted, and whether it can be undone. The remaining gaps (batch size cap, cascade behavior on children) are secondary but real for a destructive operation.

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%: targetDocumentId is documented in the schema, while nodeIds carries only minItems/maxItems constraints. The phrase 'exact node IDs' usefully signals that names or paths are not accepted, but the 200-item cap and the requirement that IDs come from figma_document are not reinforced in the description.

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 (delete nodes) plus a precision qualifier ('exact node IDs'), which is enough to place it against siblings like figma_update_nodes and figma_create_nodes. The destructive intent is unambiguous, though it doesn't explicitly name an alternative tool.

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 a clear positive condition ('explicitly requested removal') and a useful negative boundary ('cleaning nodes created by the current task'), which steers the agent away from speculative or bulk deletion. It stops short of naming a sibling tool or spelling out an explicit 'do not use for' list.

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