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

With no annotations, the description carries the full behavioral burden. It discloses the storage path and that committing shares with the team, but says nothing about whether 'set' merges or overwrites existing mappings, auth/permission needs, or failure behavior.

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?

A single front-loaded sentence with the core purpose first and a useful parenthetical tip at the end. No wasted words.

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 read/write tool with no annotations, no output schema, and 0% schema description coverage, the description is too thin. An agent cannot infer the mappings payload shape, return format, or merge semantics from it.

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 0%, so the description must compensate for both parameters. It only implies the get/set action via 'read or upsert' and adds nothing about the mappings array structure (figmaComponent, codeComponent, importPath, props, variants), leaving most semantics undocumented.

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 pair (read/upsert) and a concrete resource (the Figma→code component mapping) plus its storage location in .layerwright/mapping.json. Clear enough to distinguish from most siblings, though it does not explicitly contrast with code_scan_components or layerwright_memory.

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 description gives no guidance on when to use this tool versus siblings like code_scan_components or code_verify_usage, nor on choosing between the get and set actions. The parenthetical about committing is a workflow tip, not selection guidance.

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

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

No annotations are provided, so the description bears the full burden. 'Scan' and 'suggest' imply a read-only, non-mutating operation, which is helpful, but it does not state that nothing is written, how large codebases are handled, or what the suggestions look like. Adequate but leaves real behavioral questions unanswered.

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?

Two tightly written sentences, with the core action front-loaded and the usage cue second. No filler or repetition.

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 and no annotations, the description still conveys the action, the target files, and the result category (mappings by name), which is enough for correct invocation. It could go slightly further on what the scan returns or how mappings are keyed, but the essentials are present.

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?

There is a single optional parameter (root) with 100% schema description coverage, so the schema already explains its meaning and default. The description adds nothing about the parameter, making the baseline 3 appropriate.

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 gives a specific verb and resource — 'Scan the codebase (React/Next) for exported UI components' — plus the secondary output of suggested Figma↔code mappings. It is clear and concrete, but it never names or distinguishes itself from the close sibling code_mapping, so an agent must infer the division of labor between the two.

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 states a clear usage moment: 'Use before implementing a Figma design so existing components are reused.' That is a genuine when-to-use directive, but there is no when-not guidance and no explicit alternative (e.g., code_mapping) called out for the mapping-lookup case.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the detection logic (duplicate primitives, arbitrary Tailwind values) but does not state that it is read-only, does not perform mutations, or note any auth/side-effect expectations.

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?

Two compact sentences with the core purpose front-loaded and the specific checks appended. No filler; minor room to expand on parameter roles without bloat.

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 annotations, no output schema, and 0% schema descriptions, the definition should do more: it omits the return value shape (pass/fail details?) and the meaning of the two optional parameters. Adequate for the core action but incomplete for correct invocation.

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 0% across 3 parameters. The description loosely maps 'file' to the implementation file and 'the plan's Figma components' / 'mapped code components' to planId/figmaComponents, but it never clarifies the interplay between planId and figmaComponents or acceptable formats.

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 (verify) plus resource (implementation file against the design's plan) and details the concrete checks it performs (raw <button>/<input> duplicates, arbitrary Tailwind values). It is distinct from scan/mapping siblings, though it never explicitly names code_scan_components or code_mapping as the alternatives.

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 nature of the check implies when it applies (post-implementation verification against the design plan), but there is no explicit when-to-use, when-not, or named alternative among the many figma_* and code_* siblings.

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

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

With no annotations, the description carries the full burden and does well: it states 'NON-destructive', 'Nothing is changed', and discloses the return shape ('analysisId + grouped summary'). It doesn't cover permissions, scope limits, or how the analysisId is later consumed, so it's strong but not exhaustive.

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-loads the action and packs the transformation mapping into a scannable arrow list, with the safety guarantee and return value trailing. The leading 'Mode B.' is dead weight and the sentence is dense, but overall it is efficient.

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?

No output schema exists, but the description compensates by naming the return value and enumerating the analysis categories. Safety is explicit. It leaves the relationship between analysisId and downstream apply/execute tools unstated, which is the main residual gap for this multi-step workflow.

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 schema already documents mode (with a detailed enum), target, and verbose. The description only echoes target ('selected frame (or node id)') and adds no format or default nuance beyond the schema, so 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?

States a specific verb+resource (inspect selected frame/node, compare to Design System, propose transformations) and enumerates concrete transformation types. An agent can distinguish it from apply/execute siblings because it explicitly only proposes. The cryptic 'Mode B.' prefix adds no clarity and the tool isn't contrasted with named siblings.

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?

'Inspect the selected frame (or node id)' and 'propose NON-destructive transformations' imply this is the analysis step before applying changes, but no explicit when-to-use or when-not guidance is given. Alternatives like figma_apply_transformations, figma_preview_plan, or figma_scan_design_system are never named, leaving the agent to infer the correct routing.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that replaced originals are hidden and renamed rather than deleted, and that the operation is a single undo step. Both facts materially affect whether an agent should call it without confirmation.

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?

Five short sentences, each carrying a distinct load: source, approval gate, subsetting rule, mutation behavior, undo scope. The hard constraint (approved) is front-loaded ahead of the softer scoping 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 mutation tool with no annotations and no output schema, it covers the critical ground: approval gating, non-destructive replacement, undo semantics, and subsetting. It omits what the call returns and how the three filter parameters (ids/ops/groups/excludeGroups) compose, which is the remaining gap.

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 50% and the description adds real value for two of six params: it explains that ids selects a subset with default-all semantics, and that approved is an approval gate. It says nothing about how ops, groups, and excludeGroups interact or whether they are combinable, so half the surface remains undocumented.

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 ('Apply') and the resource ('transformations from figma_analyze_design'), which pins the operation to a known upstream artifact. It does not, however, distinguish itself from nearby siblings such as figma_execute_plan or figma_preview_plan, leaving the agent to infer which stage of the pipeline this belongs to.

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 an explicit precondition (approved=true, only settable after explicit user approval) and a scoping rule ('Pass ids to apply a subset (default all)'). It stops short of saying when to prefer this over figma_preview_plan or figma_execute_plan, so alternative-selection is left implicit.

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

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

With no annotations, the description carries the full burden, and it does disclose the most important trait: removal is gated behind approved=true and defaults to a non-destructive list. However it omits permissions needed, whether removal is reversible/permanent, and what the listing returns.

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?

A single front-loaded sentence with an em-dash that separates the list behavior from the destructive variant and closes with the default. No wasted words, though it is dense and could be split for readability.

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 tool that can delete content with no annotations and no output schema, the description covers the mode switch and defaults but leaves gaps around return contents, required permissions, and reversibility of deletion. Adequate but not complete 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?

Despite only 50% schema coverage, the description compensates by naming the filtering dimensions (session, run, node ids) and the default (this session) plus the approved=true trigger semantics. This adds real meaning beyond the two documented schema params, though nodeIds/approved still lack detailed semantics.

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 states a specific verb pair (list/remove) and the exact resource (nodes Layerwright created), scoped by session, run, or node ids. It is clear what the tool does, though it does not explicitly name or contrast itself with siblings like figma_execute_plan or figma_verify.

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 concrete context for when to reach for it ('leftovers from failed attempts') and states the default behavior (this session, list only) plus the condition that enables removal (approved=true). It lacks explicit when-not-to-use guidance or named alternatives, but the usage condition is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses the single-undo-step model, ordered execution with $n back-references, and the crucial soft-delete fallback when approved is absent (hide+rename with 🗑) versus a real removal. It stops short of describing failure/rollback behavior on partial op failure or any permission/rate constraints, which keeps it out of 5 territory.

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 single front-loaded sentence is appropriately sized for a tool with ~18 op variants, and every op clause carries some information. However, it is a run-on paragraph with nested parentheticals rather than a scannable structure, which hurts comprehension for such a dense op list.

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 complex, annotation-free, output-schema-free tool, the description covers op vocabulary, execution ordering, node referencing, and the approve/soft-delete contract. The remaining gap is error and partial-failure behavior, but the core information an agent needs to construct a valid call is present.

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 only 50%, but the description compensates by explaining op semantics the schema only names, e.g. 'resizeToFit (sections grow to their content)', 'swap ... overrides are kept', 'componentize ... works on copies by default'. The approved parameter's dual meaning (approve changes; for delete it means really remove) is also clarified beyond its schema text.

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?

Opens with a specific verb+resource ('Change existing layers in one undo step') and then enumerates the full op vocabulary, so an agent knows exactly what surface it covers. It does not, however, distinguish itself from plausible siblings such as figma_execute_plan or figma_apply_transformations, leaving the agent to infer the boundary.

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 description gives an operational precondition ('Changing or deleting existing nodes needs approved=true; without it, delete only hides and renames the node') and ordering semantics ('Ops run in order and can use "$n"'), which is genuine when-to-use context. But it never names an alternative tool or states when this tool should be chosen over siblings, so selection guidance is only implied.

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

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

With no annotations, the description carries the full burden and does a good job: it discloses that execution is a single undo step, that failure triggers a full rollback, that the result is automatically verified against the plan, and that approved=true is required when writing into an existing node. It stops short of describing permissions, connection state, or what a failed verification returns, but the mutation/risk profile is unusually well covered.

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, front-loaded with the core action, then rollback/verification guarantees, then the conditional requirement. Every sentence adds distinct information with no repetition.

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 mutating tool with no annotations and no output schema, the description covers the key risk surface (undo scope, rollback, auto-verification, approval gate). Gaps remain around how planId is obtained and what is returned on success vs. verification failure, but nothing critical to invoking it correctly is missing.

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 0%, so the description must compensate. It explains the conditional meaning of 'approved' (required when the plan writes into an existing node), which the bare boolean schema does not convey, and planId is implied to come from a prior preview. Neither parameter's format or provenance is fully specified, so it adds real but partial value.

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 states a specific verb+resource combination ('Execute a previously previewed plan in Figma') and enumerates the artifact types it produces (native frames, Auto Layout, component instances, variables, styles). The phrase 'previously previewed plan' explicitly ties it to the figma_preview_plan sibling, so an agent can distinguish it from figma_edit or figma_apply_transformations without opening any schema.

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?

Usage is implied rather than stated: 'previously previewed plan' tells the agent this must follow a preview step, and the approved=true requirement gives one concrete prerequisite. However, no sibling is named as an alternative (figma_edit, figma_apply_transformations) and there is no explicit when-not guidance, so the agent must infer the routing.

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

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

With no annotations, the description carries the burden and does disclose meaningful behavior: compareWith triggers a headless-Chrome screenshot of the source HTML and returns both images, a diff heatmap, and the share of changed pixels. It does not cover rate limits, permissions, or the plain (non-compare) return shape, so it is useful but incomplete.

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?

Two tight sentences with the primary action front-loaded and the compare mode second. The parenthetical about empty instances/sizes/variants is slightly padded but does convey the motivation for the visual check.

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 5-parameter tool with a nested object and no output schema, the description supplies the output content for the compare mode and the general purpose of the render. It omits what a plain (non-compare) call returns, which an agent would otherwise have to infer.

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 60%, and the description adds real meaning for compareWith (it explains what that object produces). But scale, format, and maxDimension are left entirely to the schema, and the description adds nothing about their interaction or defaults. Baseline 3 is appropriate.

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+resource: 'Render a Figma node as an image'. The stated intent ('check the result visually' after builds/edits) makes the job unambiguous. It does not explicitly distinguish itself from near-siblings like figma_verify or figma_inspect, so it falls short of a 5.

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 clear triggering context: 'use it after every build or edit to check the result visually', plus a named conditional mode (with compareWith) and what that mode adds. No explicit when-not-to-use or named alternative sibling is given, so it stops short of 5.

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

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

With no annotations, the description carries the full burden. It usefully discloses idempotency by name and the required post-step rescan, which is real behavioral context. However, it does not say whether existing styles not mentioned are removed, how name collisions overwrite content, or what permissions/side effects apply to a mutation of the open 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 action, followed by a dense enumeration of the five artifact types and two short operational sentences. It is long but nearly every clause maps to a parameter or behavior; only the gradient/edit nuance could be trimmed.

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 seven-parameter, nested, no-output-schema mutation tool this is reasonably complete: it covers all five artifact families, naming/token semantics, idempotency, and the follow-up rescan. It stops short of describing return values or how conflicts with pre-existing styles are resolved, leaving minor gaps.

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 14%, so the description must compensate and largely does: it defines the variable collection as COLOR/FLOAT variables with naming/value examples ('color/brand/deep-teal': '#176B66', 'radius/media': 20), and clarifies that paint styles may be a hex, a gradient, or bound to a colour variable. This adds genuine meaning beyond the sparse schema, though it never explains the 'numbers' or 'collection' parameters directly.

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 ('Create or update') and resource ('Design System foundations in the open file') and enumerates the five artifacts it manages, which map cleanly onto the top-level schema properties. It does not, however, name or differentiate itself from near siblings such as figma_scan_design_system or figma_execute_plan, so the agent must infer the relationship.

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?

Usage is implied by scope ('in the open file') and the trailing 'Rescan the DS afterwards' hints at ordering with the scan tool, but there is no explicit when-to-use/when-not or named alternative. An agent gets a rough sense of context without clear routing.

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

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

With no annotations, the description carries full behavioral burden. 'Retrieve' implies a read-only, non-mutating call and the enumerated return contents (components, tokens, styles, code mappings) add useful transparency about what comes back. However, it says nothing about permissions, limits, pagination, or how filtering by task is performed, leaving meaningful 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?

Two tight sentences with the core scope front-loaded, followed by a compact, high-signal example. Every element earns its place with no filler.

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 and no annotations, the description does a fair job describing the returned artifacts, but it omits the meaning of `limit` and `roles` and any behavioral constraints. For a 3-parameter retrieval tool with no structured support, this is adequate but incomplete.

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 only 33%, so the description should compensate more than it does. The example task string ('password reset flow: email, OTP, new password, success') usefully illustrates the `task` parameter format, but `limit` and `roles` are not addressed at all (roles is only documented in the schema), leaving part of the low coverage unresolved.

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 ('Retrieve') and resource ('Design System parts relevant to a task') and enumerates the payload (components with variants/properties, spacing/color/radius tokens, text styles, code mappings). It differentiates somewhat from siblings via the 'ONLY ... relevant to a task' scoping, though it never explicitly names alternatives like figma_scan_design_system or figma_foundations.

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?

'Use before writing a Design Plan' gives a clear when-to-use trigger, and the worked task example shows the intended input shape. It stops short of stating when NOT to use it or naming the sibling tools that also read design-system data, so no explicit exclusions are provided.

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

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

No annotations are provided, so the description carries the full burden. It reveals meaningful behavior: fidelity approach (headless Chrome + serialization of boxes/colors/gradients/shadows/radii/text/SVG), naming by screen label, and the 'almost no tokens' characteristic. It omits prerequisites (Figma connection, serving requirements beyond default root), reversibility of edits, and error behavior. Adequate but with 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?

Three information-dense sentences front-load the core purpose and then describe default behavior and a pre-step. No filler, though the opening is packed with layers that could be structured as a list for faster scanning.

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?

Given 13 parameters, no annotations, and no output schema, the description is reasonably complete for the core call but thin on behavioral contracts for the many optional parameters (swaps, components, page/section/replace semantics). It should do more to compensate for the missing annotation and output schema coverage.

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 85%, so the schema already documents most parameters. The description adds value only for dryRun and the default-targets behavior; it does not explain the complex nested structures (swaps, targets, actions) beyond what the schema and its inline descriptions already convey. Baseline 3 is appropriate.

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?

Specific verb+resource ('Import an HTML prototype into Figma') with an explicit pipeline (headless Chrome render, serialize painted result, build on page). The default behavior with no targets is spelled out ('every screen on a review board ... imported and named by its label'), distinguishing it from siblings like figma_scan_design_system.

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?

Provides clear usage context: when targets is empty, all screens on a review board are imported; 'Use dryRun to list screens first' is a concrete pre-step. However, it never names an alternative tool (e.g., import_html_to_plan / figma_execute_plan) or when to prefer those, so it does not reach 5.

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

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

No annotations are present, so the description carries the full behavioral burden. It usefully discloses that results are capped and how to work around that, plus the default target and format. It omits any mention of permissions, connection/auth prerequisites, or error behavior, so it is good but not fully complete for an unannotated tool.

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-loads the core action and target selection before the format catalog, and every clause carries information. It is dense and long, but little of it is wasted given the number of formats and parameters to document.

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 does the work of describing what each format returns, which is exactly what is needed here. Missing explanations for maxNodes and only partial guidance on expandInstances are the only real gaps for a seven-parameter tool.

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 only 43%, but the description compensates well: it fully explains all five format enum values (which the schema lists only as bare strings), the three target options, and the depth/offset/limit controls. It does not explain maxNodes or clarify expandInstances beyond the schema's own note, leaving a small gap.

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 ('Read Figma nodes') and immediately disambiguates the three possible targets (selection, page, node id). It also enumerates the five output formats with their defaults, so an agent knows exactly what the tool produces without opening the schema.

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 clear format-selection guidance ('summary ... cheap for big frames', 'plan ... send to figma_preview_plan') and routing for oversized answers ('use summary, a smaller depth, or offset/limit'). It does not, however, state when to prefer this over sibling inspection tools like figma_get_design_context or figma_analyze_design, so there is no explicit exclusion.

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

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

With no annotations, the description carries the full burden and does well: it discloses the mutation, the dry-run vs apply distinction, single-undo reversibility, override preservation, and what the report contains (instances per target variant plus no-match cases). It omits permission/auth requirements and the exact effect on unmatched instances, so not quite full marks.

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 tight sentences, front-loaded with the core action followed by the variant-matching rule and the dry-run/apply behavior. Dense but every clause carries information; no filler.

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 6-parameter mutation tool with no annotations and no output schema, the description covers the key behaviors an agent needs (preview mode, apply mode, override retention, report contents). Missing only auth/prerequisite details and edge-case handling of unmatched instances.

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 83% so the schema already documents most parameters, but the description adds meaning beyond it: it ties propertyMap/valueMap to renamed variant properties and values, and clarifies the from/to migration targets and the 'matching variant' semantics. This exceeds the baseline-3 case.

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 states a specific verb and resource: moving every instance of one component (set) to another, with concrete examples (old Accordion set to new one, library to library). This is unambiguous and hard to confuse with a generic transform tool, though it names no sibling explicitly for differentiation.

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 clearly explains the two operating modes: without 'approved' it is a dry run that reports changes, and with 'approved' it applies everything in one undo step. This gives strong context for choosing how to call it, but it never names an alternative tool or states when-not to use it (e.g., vs figma_apply_transformations).

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose two useful traits: same-named pages are reused (idempotent-ish) and an empty default page is renamed rather than kept. However, it is silent on whether pages omitted from the list are deleted, whether reordering is destructive, or what permissions are required — significant gaps for a mutation tool.

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?

Two tight sentences, front-loaded with the action and scope; the behavioral caveat follows without padding. Every clause 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 single-parameter, no-annotation, no-output-schema mutation tool, the description covers ordering and reuse but leaves the critical question of what happens to pages not listed unanswered. An agent could call it correctly but might cause unintended page loss.

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 0% for the single 'pages' array, so the description must compensate. It conveys ordering semantics ("in the given order") and name-matching behavior, which is genuinely useful, but omits the 1–40 item bounds and the per-item minLength constraint that the schema declares silently.

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 pair (create/reorder) and resource (pages) scoped to the open Figma file, plus the ordering constraint. It does not name or contrast with any sibling tool, but no sibling obviously overlaps with page creation, so an agent can identify its role.

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 description never says when to reach for this tool versus alternatives, nor states prerequisites such as needing a file open or an authenticated session. The reuse/rename clause hints at behavior but is not framed as usage guidance.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses validation semantics (Zod), that resolution happens against the cached Design System, that no Figma state is mutated, and that failures return structured errors with suggestions. It doesn't say whether validation results or the planId are persisted/cached or what permissions/state the cache requires.

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?

Two sentences, front-loaded with the action and the key constraint, followed by the return contract and the failure/recovery path. Every clause adds information; nothing is restated from the name or schema.

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 correctly supplies the return contract (planId + human-readable summary) and the error shape, which is what an agent needs to decide what to do next. Only the downstream role of the planId (e.g. passing it to figma_execute_plan) is left implicit.

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% and the single parameter already documents the DesignPlan shape and points at the figma-design skill for the DSL. The description adds the 'Design DSL JSON' framing and the validation/resolution context but no field-level meaning beyond the schema, so the baseline 3 is correct.

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 (validate/preview) and resource (Design Plan / Design DSL JSON) and pins the boundary 'WITHOUT touching Figma', which functionally separates it from figma_execute_plan without opening either schema. An agent can tell this is the dry-run counterpart to execution.

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 when-to-use context via the closing loop: 'Invalid plans or unresolved components return structured errors with suggestions — fix the plan and preview again.' That establishes the iterate-before-execute workflow. It stops short of explicitly naming figma_execute_plan as the follow-up step or stating when to skip previewing.

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

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

With no annotations, the description carries the full burden. It does disclose real behavioral traits: it normalizes and infers semantic roles, caches to disk (a side effect), and returns a compact summary rather than the full dump. However it omits whether the file is mutated, permission/auth needs, cache staleness behavior, and cost of a full scan.

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 verb and scope, two sentences total, no filler. The parenthetical '(not the full dump)' and 'Use refresh=true...' each earn their place. Slightly dense enumeration of artifacts but not padded.

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 complex scanner with no output schema and 4 params, the description covers what is scanned, the caching behavior, and the shape of the return (compact summary). It stops short of describing summary contents or read-only guarantees, but is largely sufficient to invoke correctly.

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 75%; reload, maxInstances, and includeLibraries are already documented in the schema. The description usefully compensates for the undocumented refresh parameter by explaining 'refresh=true after the DS changed,' but adds little for the other three.

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 (scan) and resource (open Figma file's design system), and enumerates exactly what is collected: components, component sets/variants/properties, variables with modes, text/paint/effect styles, and library components. It is clear and non-tautological, but it never distinguishes itself from near siblings like figma_foundations, figma_inspect, or figma_analyze_design.

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 final sentence gives one concrete usage rule: 'Use refresh=true after the DS changed.' That is a useful trigger, but there is no guidance on when to reach for this tool versus the sibling scan/inspect tools, and no statement of prerequisites (an open Figma file).

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

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

No annotations are provided, so the description carries the full burden. It does disclose a real side effect — 'Switches to the page of the first node' — which tells the agent the viewport/page state changes. However, it omits whether this requires an active Figma session, what happens with nodes on different pages, or any return value.

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?

Two short sentences, zero waste, with the core action front-loaded before the clarifying intent and the page-switch side effect.

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 single-parameter viewport/selection tool with no output schema, the description covers purpose, intent, and the page-switch behavior adequately. Only the lack of any permission/session or multi-page caveat keeps it from being fully complete.

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?

With 0% schema description coverage and one parameter, the description adds some meaning: 'node ids' identifies the array contents and 'the page of the first node' conveys that array ordering matters for the page switch. That is a genuine semantic hint beyond the bare schema, but it is thin for a required parameter.

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+resource ('Select and zoom to node ids in Figma') and adds the intent in parentheses. It is clearly distinguishable from siblings like figma_inspect or figma_execute_plan, though it never explicitly contrasts with them.

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 parenthetical '(to show the user what was created or will change)' implies the usage context — surfacing results visually — but there is no explicit when-not guidance or named alternative (e.g., when to use figma_inspect instead). Usage is implied rather than directed.

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

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

With no annotations, the description carries the full burden, and it does disclose the specific state it reports (connection, file/page, selection, scan cache) plus a cost signal ('cheap'). It does not explicitly state that the call is side-effect free, but 'Check' and the read-only nature of the listed outputs make the safety profile reasonably clear.

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?

Two short sentences, fully front-loaded with the substantive content first and the actionable 'call first' cue last. Every clause earns its place by naming a distinct piece of state.

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 must indicate what comes back, and it enumerates the reported values well. It could say more about the response shape or failure modes (e.g., what happens when the plugin is disconnected), leaving a minor gap.

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?

The tool takes zero parameters, so there is nothing to disambiguate; the schema is empty and consistent with the description. Baseline 4 applies for a parameterless tool.

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 ('Check') and enumerates the exact resources inspected: bridge connection, open file/page, current selection, and Design System scan cache. This is clearly distinguishable from siblings like figma_pages, figma_inspect, or figma_scan_design_system, which perform the actual scans or navigation.

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 directive 'Cheap; call first' gives an explicit ordering cue that tells the agent when to reach for this tool before others. It stops short of naming alternatives or when-not-to-call, but the sequencing guidance is concrete and actionable.

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

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

No annotations, so the description carries the full behavioral burden. It discloses the diagnostic scope (the five mismatch categories), which is genuine value, but says nothing about whether the operation is read-only/non-destructive, whether it mutates the document, or what permissions the plan requires. With zero annotation coverage these gaps matter.

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?

Two tight sentences with the action front-loaded and the usage note second. Every clause earns its place; nothing is redundant or padded.

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 single-parameter diagnostic with no annotations and no output schema, the description covers what it checks and when to run it. It leaves the report/return shape and the safety profile (read-only vs. mutating) unstated, which are the only notable omissions.

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?

One required parameter (planId) at 0% schema description coverage. The description's repeated reference to 'an executed plan' implies planId identifies that plan, so the parameter is inferable, but no format, source, or provenance detail is added.

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 ('re-inspect'), the resource ('nodes created by an executed plan'), and enumerates the mismatch categories it detects (missing nodes, wrong component/variant, text, layout, unbound tokens). It is clearly distinct from figma_execute_plan and figma_inspect by content, though it never names a sibling to route against.

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 timing guidance: 'Use after the user edited things or before implementing code.' That is concrete context for invocation, but it names no alternatives (e.g., why not figma_inspect or code_verify_usage) and states no preconditions beyond the plan existing.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the key safety trait ('Nothing is sent to Figma yet'), the return value (a planId), and conditional behavior (DS component substitution when a design system is scanned). It omits permissions, error behavior, and whether the plan persists, keeping it short of a 5.

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 sentences, front-loaded with the core action, and every sentence carries information (what converts, DS behavior, return value, side-effect scope). The long enumeration of converted properties is slightly run-on but still earns its place by conveying conversion fidelity.

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 compensates by naming the returned planId and its consumer. All nine parameters are schema-documented and the two-phase preview/execute pattern is explained, so an agent has enough to call it correctly; only error handling and plan lifetime are unaddressed.

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 schema already documents all nine parameters, including nested target/targets/mappings/viewport details. The description only obliquely touches parameters (the design-system sentence gestures at useDesignSystem and mappings, and it mentions fonts), so the baseline of 3 for a fully documented schema is correct.

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 states a specific verb and resource — 'Convert an HTML page or folder ... into an editable Design Plan' — and enumerates the fidelity of the conversion (flexbox→Auto Layout, colors, borders, fonts, RTL, SVG). It even names the downstream consumer (figma_execute_plan) and the analogous sibling (figma_preview_plan), so an agent can place it relative to siblings without opening a schema.

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 clearly establishes the workflow context: this produces a plan, and execution happens later via figma_execute_plan; 'Nothing is sent to Figma yet' tells the agent this is the staging step. The main gap is that it never contrasts with the sibling figma_import_html, so the agent must guess which HTML entry point to pick.

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

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

No annotations are provided, so the description carries the full burden. It discloses a meaningful side effect: this writes to a shareable file (.layerwright/memory.json) shared with the team, and that saved notes persist into the next session. That is useful non-obvious context. However it doesn't cover key behavioral questions: what 'get' returns, what 'forget' removes and whether it's reversible, what happens when a note conflicts with an existing mapping, or any rate limits. For a mutation tool with no annotations, this is incomplete.

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?

Two sentences, front-loaded with the resource location and its contents, followed by the actionable trigger. No filler words and the example is concrete. It could be slightly tighter but everything present 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?

The tool has a nested 'forget' object with five fields, a required action discriminator, no annotations, and no output schema. Despite this complexity, the description only covers the 'note' action meaningfully. An agent would not know how to read memory ('get' return shape), how to selectively forget, or how the actions interact. Too little for the schema's complexity.

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 33%. The 'note' parameter has a schema description ('the user's correction or preference, in their words') and the description echoes the note concept, so that one is covered. But the 'forget' object and its five sub-fields (all, font, note, selector, component) have no descriptions in the schema and no explanation in the prose. The description says nothing about how to target a specific memory for removal, which is the tool's most semantically complex operation. It fails to compensate for the coverage gap.

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 explains what the memory store contains (font substitutions, component mappings, user notes, recurring problems) and gives a concrete example. However, it frames the tool as a store of knowledge rather than naming its operations. The action enum (get/note/forget) is the real purpose, and the description gives 'Save a note' as an example but never covers retrieval or forgetting. An agent can infer persistence but not the full action set from the description alone.

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 one clear actionable trigger: 'Save a note whenever the user corrects you.' That covers the 'note' action well. But there is no guidance on when to use 'get' (e.g., at session start / before making substitutions) or when to use 'forget' (e.g., user retracts a preference or a mapping is wrong). Those are exactly the decisions an agent needs to make for the other two enum values, and they are left to inference.

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