figma_dev_status

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries real weight and delivers it: ordering (newest change first), exclusions (internal pages, soft-deleted nodes, superseded library copies), default inclusion semantics, neverMarked accounting, and how dating works (exportedAt/account, or fileModifiedAt for a disk read). It adds substantive behavior beyond the safety hints, though the 'see the server's instructions' deferrals are gaps.

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?

The purpose is front-loaded, and the text is information-dense with little filler, but it is a single 130-word paragraph of nested clauses and parentheticals with no structural separation of usage, output fields or constraints, making it hard to scan. Size is large for a 5-parameter tool but mostly load-bearing rather than redundant.

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 takes on return-shape disclosure and enumerates the entry fields (id, type, name, page, path, pathIds, status, raw, previous, previousRaw, changedAt, by, note, neverMarked) plus the exception cases. It is largely complete, but key mechanics such as pagination/limit behavior and refresh/caching semantics are outsourced to external docs rather than explained.

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 100%, so the baseline is 3. The description restates status semantics that the schema's own status description already covers ('none' marks that came off, 'any' is every record, default listing rule), adding only marginal clarification of how 'none' interacts with a prior 'previous' value; it does not document limit, page-exclusion or refresh beyond what the schema says.

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 opening clause names a specific resource and scope: nodes marked Ready for dev or Completed plus those unmarked since, ordered newest change first, and it points at each node's own status record (contrasting with figma_get_node's devStatus view). The verb is implicit rather than stated (it never says 'list'), and the dense clause structure blurs the statement, but an agent can still identify the resource and its filter behavior.

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?

Scope rules are given (internal-only pages, soft-deleted nodes and superseded library copies are left out; default listing covers nodes marked now or before), and figma_get_node is referenced as the per-node alternative. However there is no explicit when-to-use-this-instead-of guidance versus figma_changes, figma_diff or figma_get_node, and operational details are deferred to 'figma-reader help' rather than stated.

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