Batch rename

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

Annotations only declare the safety/idempotency profile; the description adds genuinely new behavior — per-item results `items: [{ id, ok, error? }]` and the key guarantee that one failing node does not fail the whole call, plus partial platform support. It does not mention reversibility (e.g. that an undo step can roll back renames), which is the main remaining behavioral gap.

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 tight sentences, front-loaded with the core operation and then the result semantics and platform caveat — each sentence carries information and none is padding. Slightly compressed in places ('Scope, optional type filter, optional regex' is telegraphic), but that density is efficient rather than confusing.

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, the description correctly compensates by describing the per-item result envelope and partial-failure behavior, and it covers the three operating modes. For an 8-parameter mutation tool the description plus the high-coverage schema is nearly complete; only reversibility/cleanup guidance is absent.

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 88%, so the schema already documents scope, types, regex, nodeId, session, and the idempotencyKey retry contract in detail. The description only restates 'scope, optional type filter, optional regex' and adds no format or interaction detail (e.g. how nodeId pairs with scope='subtree') beyond what the schema provides, so the baseline 3 applies.

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?

'Bulk rename by find/replace over names' states a specific verb, resource, and mechanism, which cleanly separates it from the single-node figma_rename_node and the text-content figma_find_replace_text. It stops short of naming those siblings, so an agent must infer the distinction from 'names' vs 'text'.

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 example ('turning `Frame 12` into `Card / 12`') and the mention of scope/type filter/regex imply intended usage, and the editor note ('Design; unverified: FigJam, Slides') is useful environment guidance. However, there is no explicit when-to-use-vs-figma_rename_node or vs figma_find_replace_text routing, which matters given how many rename-adjacent siblings exist.

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