figma_audit_design_system_report

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

With no annotations, the description carries the burden and mostly does: it discloses the ~5 minute audit cache and when to bypass it with forceRefresh, and that payloads are chunked to avoid a giant response. It implies read-only operation (fixes happen via separate design-side write tools) but never states it outright, nor how long a cold audit takes or what happens on an invalid/unreachable file.

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?

Front-loaded with the core action and its result, then descends into categories, drill-down, caching, and the fixability tagging. Dense but every sentence carries information; the em-dash stacking and semi-colon lists make it slightly harder to scan than it needs to be.

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?

There is no output schema, so the description does real work describing the return shape: six 0-100 category scores plus a weighted overall, non-pass findings with remediation, and a per-finding fixability classification. Gaps remain on response size, error/failure modes, and whether the score is comparable across runs.

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 the baseline is 3; the description goes beyond it by explaining the intent of the `category` parameter as the chunked drill-down path after a summary call, and by tying `forceRefresh` to the editing workflow. It adds workflow meaning rather than merely restating the enum values.

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: run a design-system health audit and return a scored report as data, with the six scored categories and weighted overall spelled out. It differentiates from the Design System Dashboard app ("no UI required", "same deterministic engine"), but never names the similarly-scoped siblings such as figma_lint_design, figma_ds_verify, or figma_get_design_system_summary.

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 explicit sequencing ("Start with the default summary, then drill into one category at a time via `category`") plus the forceRefresh condition after editing the file, and the schema repeats "prefer per-category calls over 'full'". What's missing is any exclusion or comparison against the adjacent audit/lint tools an agent might otherwise choose.

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