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

Discloses behaviors beyond annotations: List mode writes no files and is cheap, Surgical exports exact node ids without recursion, inline adds data to responses. Annotations (idempotentHint: true) are consistent; no contradiction.

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?

Concise, well-structured with bullet points and plain English. Every sentence adds value; no redundancy.

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, but description partially covers return values: manifest details for List, file writing behavior, inline data format. Could be more explicit about output structure for Default/Surgical, but sufficient for selection.

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 covers all 6 parameters (100% coverage), so baseline is 3. Description adds significant value by linking parameters to modes (e.g., 'id/name for Default', 'list: true' for List, 'ids' for Surgical) and explaining behaviors like raw and inline.

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?

Description clearly states 'Export Figma assets — icons as SVG, images as PNG' and defines three distinct modes (Default, List, Surgical), making the tool's purpose specific and differentiating it from 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?

Explicitly explains when to use each mode: Default for recursive export, List for cheap discovery (recommended first), Surgical for specific node ids. Provides clear alternatives within the tool.

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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds value by explaining that it is heuristic, reports only failures, and a clean result does not imply full accessibility. This provides behavioral context beyond annotations.

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 description is a single paragraph that efficiently conveys purpose, usage, and limitations. It is well-structured but slightly verbose with examples of checks; still, every sentence adds value.

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 no output schema, the description explains what findings contain (note + raw data) and limitations. With only one parameter and good annotations, the description is fully self-contained.

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 single parameter 'doc' is described in the schema as 'A full PdsDocument object', but the description adds specificity: 'pass the raw JSON response from a prior plumb_node/plumb_outline/plumb_query call', clarifying the expected format and origin.

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 clearly states the tool performs a heuristic accessibility audit over a PDS snapshot, specifying the checks (text contrast and touch-target size). It distinguishes itself from sibling plumb_* tools by focusing on audit, not extraction or manipulation.

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?

Explicitly states when to use: after getting a PDS snapshot from plumb_node/plumb_outline/plumb_query. Also mentions what it does not do: it is not a certified WCAG audit, heading-order/missing-alt-text checks are missing, and it reports only failures.

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?

Annotations provide minimal behavioral hints (readOnlyHint=false). The description compensates fully by detailing the entire process: reference discovery, live screenshots, CSS computation, palette synthesis, assembly, compilation, and execution via plugin. It also specifies return values (references, palette, root node id) and a prerequisite (plugin pairing). No contradictions with annotations.

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 description is structured with a concise opening sentence that captures the core action, followed by a detailed process explanation, return values, and a prerequisite note. While informative, the second sentence is lengthy and could be slightly more terse without losing meaning.

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?

Despite lacking an output schema, the description explicitly states what is returned (references, palette, root node id). It covers inputs, workflow, outputs, and prerequisites (plugin pairing). The tool is well-situated among siblings with clear differentiation. No gaps are evident.

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 baseline is 3. The description adds value by explaining how the 'brief' drives reference discovery and palette, noting 'count' defaults to 4, and specifying that 'references' are studied ahead of discovered ones. This contextualizes parameter usage beyond schema descriptions.

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 clearly states it 'Direct a brand board' and 'BUILD it into the paired Figma file'. The verb+resource are specific, and it distinguishes itself from sibling tools by describing the unique pipeline (reference discovery, screenshotting, CSS computation, palette synthesis) and explicitly mentioning the same write path as plumb_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 description implies usage for creating a brand board from a one-line brief and contrasts with plumb_design by noting the shared write path. However, it does not explicitly state when to use this tool versus alternatives like plumb_design or plumb_scan_references, nor does it provide exclusions.

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?

The description adds behavioral context beyond annotations: it notes the tool requires the Plumb plugin ('Plugin path; needs the Plumb plugin paired') and explains that the health parameter is purely additive. No contradiction with annotations.

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 description is front-loaded with the main purpose and each sentence adds value, but it is somewhat lengthy. Could be more concise while retaining key 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?

Given no output schema, the description explains what each component and instance carries (instance count, component id) and details on the health report. This is sufficient for a listing tool, though it could mention the response structure more explicitly.

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 100% schema coverage, the description still adds value for both parameters: for 'page' it notes it's a massive token saver on files with many components, and for 'health' it clarifies default false and no shape change. This goes beyond the schema descriptions.

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 clearly states it lists every Figma component definition and instance usages, distinguishing it from sibling tools like plumb_outline or plumb_node, and specifies its utility for understanding the design system before building.

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 provides clear context for when to use the tool ('useful for understanding the design system before building') and explains the optional health report. However, it does not explicitly state when NOT to use it or suggest alternatives.

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds meaningful behavioral context: output is text-only per-region narrative and flat child summary derived from PDS. No contradictions with annotations.

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 delivering purpose, use cases, output format, and sibling guidance with no superfluous content. Front-loaded and 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?

Given 5 parameters and no output schema, description explains return narrative and summary, mentions derivation from PDS, and links to siblings. Lacks parameter-specific behavior details but sufficient for most agents.

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 covers all 5 parameters with descriptions (100% coverage). The description does not add extra meaning beyond schema; it only summarizes output format. 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?

The description clearly states it provides a 'text-only visual description of a Figma screen or node', specifies use cases (image-blind harness, sandboxed Read, token-conscious flows), and distinguishes from siblings by suggesting pairing with plumb_node and plumb_screenshot for complementary info.

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?

Explicitly says when to use (when screenshot cannot be read) and when to pair with other tools (plumb_node for structural spec, plumb_screenshot for pixel reference), providing clear context versus alternatives.

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?

Fully discloses behavior: write operation, the pipeline (validate, compile, lower, execute), side effects (touches Figma unless dryRun), output format (node ids keyed by handle). No contradiction with annotations.

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?

Concise, front-loaded with core action, well-structured without fluff. Each sentence adds value.

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 the complexity (8 params, nested objects, no output schema), the description is complete—covers purpose, process, parameters, output, and integration with siblings.

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?

All 8 parameters have schema descriptions (100% coverage), and the description adds contextual meaning, e.g., explaining dryRun returns plan stats, and tying parameters like mode and prune to the workflow.

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 clearly states the tool authors a design from a DSL and builds it into Figma. It specifies the write direction and distinguishes from siblings by mentioning the output feeds into plumb_review/motion.

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 context for use (authoring/building, dryRun for sanity-check, modes create/sync) but does not explicitly exclude other tools or give when-not 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?

The description discloses output format (structured deltas with summary, not JSON diff), narration using role labels, and the fact that it only compares two documents. Annotations (readOnly, idempotent) are consistent and description adds value beyond them.

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 description is a single well-structured paragraph that covers purpose, prerequisites, output format, and constraints without wasted words. Every sentence adds value.

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 the tool's simplicity (2 params, no output schema), the description fully covers what the tool does, how to use it, and what to expect in return. It is complete for an AI agent to use 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 coverage is 100%, but the description adds meaning by explaining that parameters must be full PdsDocument objects from specific tools and that nodes+root fields are required. This provides context beyond the schema.

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 clearly states it performs a semantic diff between two PDS snapshots of the same screen, specifying the verb (diff) and resource (snapshots). It distinguishes from siblings by noting it does no live Figma fetching.

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 provides explicit usage instructions: call plumb_node (or outline/query) before and after a change, then pass the responses here. It clarifies what it does not do (no live fetching), but does not name explicit alternatives.

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?

The description adds significant behavioral context beyond annotations: it is template-based, deterministic, not an LLM call, and warns about vector nodes and images. This complements the readOnlyHint, openWorldHint, and idempotentHint annotations well, and there is no contradiction.

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 description is front-loaded with the core purpose and is well-structured. Every sentence adds value, covering input, behavior, and output characteristics. It is concise for the amount of information provided.

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 the tool has 2 parameters, no output schema, and no nested object details, the description covers the input sources, deterministic nature, and output caveats (warnings for vectors/images). It provides sufficient context for an agent to understand the tool's role in the pipeline.

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 100% schema description coverage, the baseline is 3. The description adds meaning by explaining that the 'doc' parameter auto-detects between Figma and WebSpec documents, and that 'componentName' has a default of 'GeneratedComponent'. This provides clarity beyond the schema.

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 clearly states it is a deterministic code generator for React JSX from PDS or WebSpec documents. It specifies the input sources (plumb_node/plumb_outline/plumb_query or plumb_import_web) and that it outputs pixel-faithful JSX+inline styles. This distinguishes it from sibling tools like plumb_outline which provide outlines, not code.

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 explains to pass raw JSON from prior plumb calls and notes that the output is pixel-faithful, not responsive, guiding appropriate usage. However, it does not explicitly mention when not to use this tool or alternative tools for responsive design.

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?

Annotations declare readOnlyHint true and idempotentHint true. Description adds detail about returned fields (type, name, size, etc.) and special handling for TEXT nodes, which supplements the annotations without contradiction.

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 action, no redundant words. Every sentence adds value.

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 only 2 simple parameters, no output schema, and no nested objects, the description covers all essential aspects: what the tool does, how to use it (pair with outline), and what it returns (list of node properties). No 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 coverage is 100% with descriptions for both parameters. Description adds extra meaning by specifying the id format as 'sessionID:localID' and noting it comes from plumb_fig_outline, which is helpful beyond schema.

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?

Description uses specific verb 'Read', identifies resource as 'one node from a saved .fig file', and clarifies the id format. It distinguishes from sibling tool plumb_fig_outline by stating the pairing 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?

Explicitly instructs to pair with plumb_fig_outline to find the id first, providing clear context. Does not include explicit when-not-to-use alternatives, but the context is unambiguous.

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?

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context: reads from disk, lists screens across all pages, and has no external dependencies. No contradiction.

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 action. Every phrase earns its place; no waste.

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 the tool's simplicity (one param, no output schema), the description fully covers purpose, usage, and behavior. No 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 100% for the single parameter figPath. The tool description does not add further parameter meaning beyond what the schema already provides. 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?

The description clearly states the tool reads a .fig file and lists screens across pages. It distinguishes itself from sibling plumb_outline by noting it works without Figma desktop, plugin pairing, or FIGMA_TOKEN.

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?

Explicitly specifies when to use: 'when you've exported a .fig file and need to inspect or implement screens without opening Figma.' Implicitly contrasts with plumb_outline, providing clear context and alternatives.

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?

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context: the tool is called repeatedly with rendered data from the agent's build tags, expects convergence, and returns scores and fixes. It warns about stalling and advises reading deltas and coverage. This goes beyond annotations.

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 description is a structured numbered list that is easy to follow. It is somewhat verbose but each sentence serves a purpose: defining the loop, input requirements, output fields, and expected behavior. Minor redundancy could be trimmed, but overall efficient for the complexity.

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 the tool has 9 parameters, nested objects, no output schema, and is part of an iterative process, the description covers the essential workflow, input expectations, and output interpretation. It mentions the key return fields (score, done, topFixes, bar, instruction) and hints at deltas/coverage. Lacks explicit output structure details but sufficient for the iterative use case.

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 schema documents all parameters. The description adds value by explaining the rendered parameter shape is the same as plumb_verify, and how the iteration parameter sharpens coaching. This semantic linking helps the agent understand data flow.

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 clearly states it is a 'self-healing build loop' for iterative pixel-perfect matching, distinct from one-shot checks. It names the verb 'iterate' and identifies the resource as visual builds. It differentiates from the sibling plumb_verify by emphasizing iteration.

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 explicitly says to use this for iterative refinement instead of a one-shot check, implying when-not-to-use. It provides a step-by-step loop. However, it does not explicitly list alternative tools or exclusion criteria beyond the contrast with one-shot checks, which are implied to be plumb_verify.

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?

Description adds beyond annotations: drives headless Chrome, skips hidden elements, returns real CSS values and fontLinks. Annotations already declare readOnlyHint=true, so no contradiction. OpenWorldHint=true aligns with external webpage dependency.

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?

Description is dense but well-structured, front-loaded with purpose. Could be slightly trimmed (e.g., fontFamily detail), but every sentence adds value. Appropriate length for a complex import tool.

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, but description explains return format for viewports and mentions fontLinks. Covers all params and use cases. Adequate for a tool with 3 params and rich behavior.

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%, giving baseline 3. Description adds significant value for 'viewports' (explains true as default set, result shape) and 'selector'. Provides context beyond schema descriptions.

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 clearly states the tool imports a live webpage's structure and semantics into a Semantic Graph, using specific verbs and resource (import web). It distinguishes from sibling tools like plumb_node and plumb_audit.

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?

Explicitly states when to use (understand site structure, audit, track over time) and provides alternatives (plumb_audit, plumb_diff). Mentions that no Figma connection is needed, clarifying a non-use 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?

Annotations already provide readOnly, openWorld, idempotent hints. Description adds significant behavior: deduplication, auto-layout resolved to flexbox, duplicate handling, expandAll with token budget, auto-trimming, and collapseRoles 'more' contract. Adds value beyond annotations.

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?

Single paragraph of 5 efficient sentences, front-loaded with main purpose. No wasted words, clear structure, easy to scan.

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 9 parameters and no output schema, description covers extraction behavior, paths, depth control, expandAll budget, collapseRoles, and output format. Sufficient for agent to understand and 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 coverage is 100%, but description adds context for dual path usage and interplay between expandAll, depth, maxTokens. Explains collapseRoles semantics. Schema gives basics; description enriches understanding.

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?

Description clearly states it extracts a Figma screen or node as a normalized PDS with deduplicated tokens and CSS-shaped node tree. It distinguishes between plugin and REST paths, differentiating it from siblings like plumb_outline or plumb_tokens.

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 explicit guidance on when to use plugin path (with paired plugin) vs REST path (fileKey+id). Handles duplicate names with match list. Lacks direct comparison to other sibling tools for when to choose this over alternatives, but context 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?

Annotations already declare readOnly, openWorld, and idempotent. Description adds that it's 'cheap' and 'shallow', and explains file key auto-extraction and plugin pairing behavior, providing useful context beyond annotations.

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 description is three sentences, front-loaded with the main action, and contains no unnecessary words. Slightly more structured formatting could improve scannability, but overall good.

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 no output schema, the description adequately explains the return structure (pages and top-level screens with id, name, size). Annotations cover safety and idempotence. The tool's role among siblings is clear.

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 parameters are well-documented. Description adds minor context about URL types and file key omission, but does not significantly enhance parameter understanding beyond the schema.

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 clearly states the tool maps a Figma file's pages and top-level screens with specific fields (id, name, size), and distinguishes itself from plumb_node as the shallow entry point.

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?

Explicitly tells when to use this tool (to find screens cheaply) and when to use plumb_node (to extract a screen), and notes the plugin pairing eliminates the file key need.

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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), description adds detail: what skeleton drops (chars, fills, effects), how buttons are tagged, that text filters by font-size, etc. No contradictions.

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?

Single dense paragraph, front-loaded with purpose, no redundant sentences. Every sentence adds value: purpose, usage, examples, parameter clarification.

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?

Despite 9 params and no output schema, description covers all patterns, scoping options, parameter interdependencies, and use cases. Answers likely questions about when to use which select value and how to scope queries.

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 has 100% description coverage, but description adds context: explains 'select' enum options, clarifies 'role' is required for select:'role', and notes fileKey omission condition. Adds meaning beyond schema for each param.

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?

Description states it queries a Figma subtree by pattern, not dumping the whole tree, and lists specific patterns (skeleton, buttons, text, components, role). It distinguishes from plumb_node by noting it's for dense screens where plumb_node would be too large.

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?

Explicitly says 'Use this on dense screens where plumb_node would be too big' and lists when each select pattern is appropriate (e.g., 'pull a skeleton', 'every button'). Also notes scope-resolution mirrors plumb_node.

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?

Annotations declare readOnlyHint=true and idempotentHint=true. The description adds context that the tool uses the same verify engine as plumb_verify/plumb_fit, that there is no server-side vision call for the director, and describes the return values. No contradictions.

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 description is overly long (over 600 words) and lacks structured formatting like bullet points. While detailed, it is not concise and could be more organized for quick parsing.

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 the complexity (13 parameters, nested objects, no output schema), the description is extremely comprehensive, covering the full workflow, axes, return fields, and iteration logic. It leaves no 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 coverage is 100% and the description adds meaning to each parameter beyond the schema, explaining their roles (e.g., ids as join key, director as vision grade) and interactions (e.g., director presence reshuffles weights).

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 clearly states that the tool self-critiques the emitted Figma design and coaches the refine loop. It distinguishes itself as the 'write-direction mirror of plumb_fit' and specifies three axes (STRUCTURE, DESIGN, DIRECTOR), providing a specific verb and resource.

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 provides explicit when-to-use and how-to-use guidance, including the canonical loop with plumb_screenshot and plumb_design. It also explains when not to use alternatives and includes prerequisites like passing EmitResult.ids.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that it streams live progress to Plumb Studio, uses the same structural pipeline as plumb_import_web, and returns data for reasoning without composing or building. These details go beyond annotations and provide a comprehensive behavioral picture with no contradictions.

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 description is a single paragraph that is information-dense but not overly verbose. Each sentence adds value: purpose, extraction details, streaming, usage guidance, contrast with sibling, and return behavior. Minor improvements could be made by breaking into shorter sentences, 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?

Given no output schema, the description explains that the tool returns data for reasoning and folding into plumb_design DSL or plumb_studio brief, and specifies the type of extracted content (nav/hero/footer/card exemplars). This covers the output sufficiently. However, the exact structure or format of the digest is not detailed, preventing a perfect score.

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 only parameter 'references' is fully described in the schema (100% coverage) with min/max items and description. The description does not add additional parameter-level detail beyond restating 'up to 8'. Per guidelines, baseline is 3 when schema coverage is high, and no extra value is added here.

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 clearly states the tool scans N live reference URLs and extracts a per-role STYLE DIGEST of concrete design elements. It distinguishes itself from sibling plumb_brand by clarifying it captures structural features, not just colors, and explicitly says it does not compose or build anything, making the purpose unambiguous.

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 explicitly states 'Use this BEFORE plumb_studio/plumb_design' when structural resemblance is desired, and contrasts with plumb_brand for color palette extraction. This provides clear when-to-use and when-not-to-use guidance, differentiating the tool from siblings effectively.

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?

Discloses that it saves a file locally and returns the path. Also mentions the need for the Plumb plugin, which is important behavioral context beyond the annotations (idempotentHint=true). No contradiction.

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 plus one about plugin path. Front-loaded with the main action. No unnecessary 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?

Covers purpose, usage context, plugin dependency, and basic output. Could mention collision handling or idempotency explicitly, but the schema covers those details.

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 covers 100% of parameters with descriptions. The tool description adds minimal extra meaning beyond stating it renders a Figma screen or node, which ties to id and name parameters.

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?

Clearly states the action (render), resource (Figma screen or node), and output (PNG/JPG file locally saved, returning file path). Distinguishes itself from sibling tools by being the only screenshot 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?

Explicitly mentions using it as a visual reference for building UI and as a source for plumb_verify, providing context for when to use. No explicit exclusions or alternatives, but the context 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?

Annotations already indicate safe read-only and idempotent behavior. The description adds valuable context: the plugin requirement, which is a critical dependency, and specifies the exact return fields (id, name, type, page, size). This goes beyond the annotations to disclose operational constraints.

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 sentences, no fluff. First sentence states purpose with examples, second lists output and related tools, third notes the plugin dependency. Every sentence 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 description is complete for a search tool with three optional params and no output schema. It explains return fields, filter behavior, and provides pointers to next-step tools. The plugin dependency is critical context.

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%, but the description adds meaning: explains that query is a case-insensitive substring match, page filtering is case-insensitive and substring-friendly, and provides an example for type filtering. These clarifications help the agent use parameters correctly.

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 clearly states it finds nodes by name and/or type, with concrete examples. It distinguishes from siblings by pointing to plumb_node and plumb_assets for further actions.

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 explicit guidance: plugin dependency, when to use alternatives (plumb_node, plumb_assets), and filtering options. Effectively tells the agent when and how to use the tool.

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?

Annotations already indicate readOnly and idempotent behavior. The description adds that there is no authentication or rate limiting, and that output matches plumb_node. This provides meaningful context beyond annotations without contradiction.

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 sentences, each earning its place: first gives purpose and key advantages, second clarifies output, third gives usage guidance. Efficient and well-structured.

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?

Despite lacking an output schema, the description references a known output format (compact PDS like plumb_node), which is sufficient given the family of tools. The tool's behavior and invocation context are fully covered.

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 schema documents parameters adequately. The description does not add further detail about depth, notes, or maxTokens beyond the schema.

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 clearly states the tool extracts the user's Figma selection via the Plumb plugin, with notable benefits (no file key, token, rate limit). It distinguishes from plumb_node by specifying the source (selection vs. node) while noting identical output format.

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?

Explicit guidance is provided: 'Prefer this when plumb_status shows the plugin connected and the user says build this about their Figma selection.' This tells the agent exactly when to use this tool over alternatives.

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?

The description goes beyond annotations by detailing parallel queries, keyless-first providers, ranking logic, mode behavior, and fallback to placeholder. Annotations are minimal (openWorldHint, no readOnly), so the description adds valuable behavioral context.

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 description is well-structured: opening statement, provider details, mode breakdown. Each sentence adds value, and the format is front-loaded with key information.

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 the complexity (14 parameters, two modes, no output schema), the description covers behavior, modes, providers, and fallback. It lacks explicit output structure for search mode, but is otherwise thorough.

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 schema already describes all parameters. The description provides some context (e.g., mode semantics) but does not add significant meaning beyond the schema's descriptions.

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 clearly states the tool's purpose: sourcing design assets (icons, photos, etc.) from the open web. It distinguishes itself from sibling tools by focusing on asset sourcing with ranking and two modes.

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 explains when to use search (cheap exploration) vs fetch (downloading), and notes provider availability. It does not explicitly mention when to avoid this tool or list alternatives, but the context 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds context about what the status report contains (data paths, screen count, etc.) and that no Figma access is required, which is valuable beyond annotations.

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 description is efficient with one strong imperative sentence followed by supporting details. The promotional sentence about alternatives adds some length but is contextually relevant. 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 parameterless status tool, the description fully captures what the agent will get (data paths, screen count, legend, token budget) and provides usage context (call first, no Figma access needed). No output schema is needed given the detailed enumeration.

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 are zero parameters, and schema coverage is 100% (trivial). The description does not need to add parameter info; the baseline of 4 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?

The description clearly states that the tool returns status and self-description, and should be called first. It enumerates specific outputs (available data paths, screen count, key legend, token budget), distinguishing it from sibling tools.

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?

Explicitly instructs 'call this FIRST', notes no Figma access needed, and contrasts with alternatives (official MCP, Framelink) with specific conditions where Plumb is preferable (plan-gated, token cap, 429 errors).

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?

Annotations indicate readOnlyHint=false, meaning it's a write operation; the description confirms it builds into the Figma file. It details the entire process (reference discovery, screenshotting, palette synthesis, page composition, build path) but does not add much beyond what annotations already imply. However, the level of detail is sufficient for understanding the tool's 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?

The description is relatively long but each sentence provides valuable information about the tool's process, output, and usage. It is structured well, front-loading the main action, and avoids redundancy. Slight verbosity is acceptable given the complexity.

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, but the description clearly lists the returned items: picked references, palette, node ids, and authoredPath. It also tells the agent to feed these into plumb_review. This makes the tool's input/output contract complete and actionable.

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 input schema covers 100% of parameters with descriptions. The description adds further context for each parameter: brief drives discovery/palette/copy; count has default 4; pageName default 'Studio'; references are prioritized. This enriches the schema information and helps the agent use the tool correctly.

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 explicitly states that the tool directs a full landing page from a one-line brief and builds it into Figma. It distinguishes itself from sibling tools like plumb_design by mentioning the same write path, and from other plumb_studio_* tools by being the 'headline director-completion 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?

The description explains that the tool is used when given a brief to produce a full page, and it directs the output to be fed into plumb_review for the critique loop. It does not explicitly state when not to use it or list alternatives, but the context of the brief and the detailed process implies its specific use 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?

Annotations indicate readOnlyHint=false (mutation), and the description confirms building and placing components. It adds behavioral context: the masters inherit the session palette and type scale. However, it does not disclose whether the operation is idempotent, what happens on overwrite, or error cases. The added value is acceptable 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?

Three concise sentences with no filler. The critical label 'STEP 2' is front-loaded, and every sentence adds value: purpose, behavior, linkage to next step, and prerequisites.

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 with two parameters and no output schema, the description covers purpose, key behavioral traits (inheritance), and flow context. It lacks explicit mention of return values or error handling, but given the simplicity, it is reasonably 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?

Schema coverage is 100% with only two parameters. The description reinforces the meaning of sessionId (from plumb_studio_start) and implies pageName (onto a named page). It adds marginal context beyond the schema descriptions, meeting the baseline for a well-documented schema.

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 uses a specific verb (build) and resource (component library), listing concrete component types (Button, FeatureCard, etc.). It clearly distinguishes itself as STEP 2 in a flow and names the succeeding tool plumb_studio_page, making its role unambiguous relative to 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?

The description explicitly states it is STEP 2 of the studio flow, requires a sessionId from plumb_studio_start, and advises following with plumb_studio_page. It also mentions the Plumb plugin prerequisite. While it does not give explicit when-not-to-use or alternatives, the sequential guidance is clear 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?

Description adds context beyond annotations: it instantiates component library and reuses brand imagery, implying mutation and non-idempotency (matching annotations). It also explains the output structure and follow-up actions. However, it could be more explicit about potential side effects like overwriting existing pages.

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?

Description is fairly concise with no wasted sentences; each sentence serves a purpose (step number, action, output, instructions, requirements). Slightly wordy but well-structured.

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 no output schema, the description fully explains the return value and what to do with it. It covers prerequisites, the flow ordering, and a high-level overview of the tool's action. Complete for this 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 coverage is 100% with descriptions, so description adds only marginal value by contextualizing the 'kind' parameter as a list and mentioning sessionId's source. Baseline score 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?

Clearly states the tool composes a product page (specific verb+resource) and positions it as STEP 3 in a repeatable studio flow, distinguishing it from sibling tools like plumb_studio_start and plumb_review.

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?

Explicitly states when to use (after plumb_studio_start, before plumb_review) and that it should be called once per page. Provides clear context on the overall flow, though it doesn't explicitly describe when not to use it.

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?

The description discloses that the tool mutates state (builds a board, opens a session) and specifies the outputs (sessionId, name, brand, references). This adds context beyond the annotations (readOnlyHint=false) by detailing what is created. It does not mention destructive behavior or idempotency, but the creation-oriented nature is 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?

The description is efficiently structured: a bold 'STEP 1' header, a concise three-sentence body that covers the function, flow position, outputs, and prerequisite. Every sentence adds value, and the most critical information is front-loaded.

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 the tool's complexity (multiple sub-actions), the description comprehensively covers the workflow, outputs, and flow integration. No output schema is provided, but the description lists return values. It also mentions the required plugin and gives follow-up steps, making it complete for an agent to use 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 100%, so each parameter is already documented. The description provides minimal additional meaning beyond the schema: it clarifies 'one-line brief' and default for count, but does not add substantial new constraints or format details. 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?

The description clearly states the tool's purpose as 'STEP 1 of the transparent studio flow' and details the actions: discover references, screenshot, synthesize palette, build board, open session. It distinguishes itself from sibling tools by specifying it's the first step and naming the subsequent tools (plumb_studio_kit, plumb_studio_page).

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 explicitly outlines the usage context: it's the initial step in a flow, with clear follow-up instructions ('Follow with plumb_studio_kit(sessionId), then plumb_studio_page(sessionId, …)'). It also mentions a prerequisite ('Requires the Plumb plugin to be paired'). However, it does not provide explicit when-not-to-use scenarios or alternatives beyond the flow.

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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, indicating a safe, idempotent read operation. The description adds behavioral details: the token table is deduplicated, uses $-prefixed refs, and has two access modes (plugin vs REST). No contradiction with annotations.

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 description is three sentences, each earning its place: purpose, plugin path, REST path. It is front-loaded with the core definition and uses precise terminology. 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?

Given the moderate complexity (4 params, no required, no output schema), the description explains the tool's purpose, the two usage modes, and how parameters differ across modes. It omits details about error handling or return format beyond '$-prefixed refs', but that is acceptable without an output schema.

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 covers all 4 parameters with descriptions (100% coverage), so baseline is 3. The description adds significant value by explaining the conditional usage patterns: plugin mode uses id or name (no fileKey), REST mode uses fileKey and id. It also mentions that url can be pasted for auto-extraction, but this is in the schema. Overall, the description clarifies how parameters relate to each other.

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 clearly specifies the action ('Extract'), the resource ('the deduplicated design-token table for a Figma node'), and the output format ('as the $-prefixed refs'). It also distinguishes from siblings by focusing explicitly on design tokens, unlike plumb_assets or plumb_describe.

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 provides explicit guidance on when to use the plugin path (pass id or name, no fileKey) vs the REST path (pass fileKey + id). It also advises to build with these tokens, not magic numbers. It does not explicitly list alternatives among the many siblings, but the use case is clearly scoped.

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?

Annotations declare readOnlyHint=true and idempotentHint=true, and the description adds rich behavioral context: deterministic, no pixel diff, error on missing assets, content-aware on placeholder text. This substantially extends beyond the annotations by explaining exact return structure and coverage metrics.

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 description is verbose and contains multiple paragraphs with extensive detail. While the information is valuable, it could be more concise. The main purpose is front-loaded, but subsequent sections could be streamlined for easier 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?

For a tool with 8 parameters, nested objects, and no output schema, the description is quite comprehensive. It covers input format, delta kinds, coverage, and error conditions. However, it lacks a concrete example of the output, which would enhance completeness given the absence of an output schema.

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 baseline is 3. The description adds value by explaining the 'rendered' parameter in detail (how to tag elements, what properties to include) and the 'tolerances' parameter (thresholds). It also clarifies the 'asset' field and 'img' boolean, which are not fully explained in the schema.

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 explicitly states the tool's purpose: 'Compare what you built against the Figma design and return structured deltas'. It uses a specific verb ('compare') and resource ('Figma design'), clearly distinguishing it from sibling tools like plumb_diff (which likely compares two designs) and plumb_audit.

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 explains when to use the tool: after rendering, to verify against Figma. It details prerequisites (data-plumb-id tagging) and behavioral nuances (content-aware on text, QA-strict on appearance). It does not explicitly list alternative tools or state when not to use, but the context is clear.

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