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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool searches a 'configured portable bundle' with checksum-addressing, references importing via figma.loadBundleAsset, and prohibits drawing placeholders when a bundled asset exists. This adds meaningful context beyond the schema, though it does not explicitly state read-only behavior or describe return format.

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 core purpose. It contains no filler and every sentence earns its place: purpose, preferred ID usage, and integration/usage rule. This is appropriately sized 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?

Given no output schema and no annotations, the description provides enough context for an agent to select and invoke the tool: it defines the search scope, asset types, preferred query source, and how to import results. It could mention return format or reload side effects, but it is largely complete for a search 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 description coverage is 100%, so the baseline is 3. The description adds limited parameter meaning: 'Prefer an exact semantic asset ID from design_system_plan' clarifies the intended use of the query parameter, but it does not elaborate on limit, reload, source, or category beyond what the schema already states. The schema descriptions are already comprehensive.

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 opens with a specific verb and resource: 'Search the configured portable bundle for checksum-addressable semantic assets, component SVGs, icons, merchant marks, and raster images.' This clearly identifies the tool's function and enumerates asset types, distinguishing it from sibling tools like design_system_plan or figma_read, which serve planning and reading roles.

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 using the tool: prefer an exact semantic asset ID from design_system_plan, and import a result inside figma_write with figma.loadBundleAsset. It also states a behavioral rule ('never draw a placeholder when a required bundled asset exists'). However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 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 must convey behavioral traits. It lists the contents (font dependencies, spacing tokens, typography roles, etc.) and mentions the optional recipe with Auto Layout blueprint, adding context. Yet it does not disclose whether the operation is read-only, has side effects, or requires specific configuration or permissions.

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 only two sentences long, with the first sentence front-loading the core purpose and the second adding useful content details and a directive. No wasted words, making it concise 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?

With no output schema, the description gives a good sense of what is returned by listing the categories of rules and mentioning the optional recipe blueprint. However, it does not specify the exact output structure or what 'prompt-ready' means in terms of formatting, leaving a slight gap in completeness.

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 three parameters have detailed descriptions in the schema (recipe, reload, sessionId), covering 100% of the parameters. The description itself adds no parameter-specific information, so it relies entirely on the schema, justifying the baseline score.

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 loads prompt-ready semantic design-system rules from a configured bundle, using the specific verb 'load' and naming the resource. It also distinguishes itself from guessing values from screenshots, which sets it apart from sibling tools like figma_read.

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 directs users to 'Use this instead of guessing values from screenshots', providing a clear use case. However, it does not name alternative tools or detail when not to use them, so guidance is clear but not exhaustive.

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 determinism, bundle-backed behavior, and the planning scope across many components, and it clarifies that the tool is a planning step, not a write operation. However, it does not mention potential side effects, return format, or failure modes, though the absence of such is less critical for a planning 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?

The description is three sentences: a clear purpose statement, a breakdown of plan components, and a mandatory usage directive. Every sentence earns its place, and the most important 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?

Despite no output schema, the description enumerates the plan's contents (intent, patterns, recipes, states, references, assets, flow, checklist) and specifies its role in the workflow. This gives a complete picture of what the tool produces and how to invoke it, which is strong for a complex planning 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?

The schema covers 100% of parameters with meaningful descriptions, so the baseline is 3. The description adds the directive to pass the complete request rather than a shortened keyword, but this largely echoes the prompt parameter's schema description and does not add new meaning for the other 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?

The description clearly states the tool turns natural-language design requests into a deterministic, bundle-backed generation plan, and enumerates the plan components (product intent, screen patterns, recipes, states, candidate references, assets, flow, checklist). It distinguishes itself from siblings by explicitly being the mandatory precursor to figma_write.

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 instructs that the tool is 'MANDATORY before figma_write whenever a design-system bundle is configured', which provides strong when-to-use guidance. It also tells the user to pass the complete request rather than a shortened keyword, further clarifying the expected usage pattern.

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 provided, the description carries full burden. It discloses the read-only nature via 'inspect' and 'preflight' and describes the outputs (bundle version, recipes, fonts, readiness), giving the agent a strong sense of what to expect. It does not explicitly mention side effects, but the wording implies no mutation, which is adequate for this tool type.

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 two sentences, front-loads the purpose, and every clause adds value (action, return data, usage timing). No fluff or 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?

Despite lacking an output schema, the description enumerates the return fields, covering the essential behavioral contract. It does not detail error conditions or interpretation of readiness, but for a status/preflight tool with one optional param, it is sufficiently 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 description coverage is 100%, with the 'reload' parameter fully described in the input schema. The description adds no additional parameter detail, so a baseline score of 3 is appropriate because the schema does the heavy lifting.

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 action ('Inspect', 'run dependency preflight') and specific resource ('configured portable design-system bundle'). It lists the exact return values, distinguishing it from sibling tools like figma_status and design_system_assets.

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 instructions to call before generating design-system-compliant work provide clear use context. While no alternatives or exclusions are named, the timing and purpose are unambiguous, so this meets the 'clear context, no exclusions' level.

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 of behavioral disclosure. It explains the default behavior (no-args returns quick-start + critical rules), what each section returns, and the ordering constraint relative to figma_write. This is rich contextual transparency for a read-only documentation 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?

The description is well-structured and front-loaded: it opens with the main purpose, immediately instructs to call with no args first, then lists the sections with parenthetical details, and ends with a critical rule. Every sentence earns its place; 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 tool with a single optional parameter and no output schema, the description is remarkably complete. It covers invocation patterns, section-specific content, and the workflow constraint. An agent has all necessary information to call the tool 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% and the schema already gives useful descriptions for the 'section' parameter. The tool description adds extra detail by enumerating example contents for each section (e.g., 'design principles, token rules, layer order' for rules), helping the agent choose the right section. This goes beyond the schema, so 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 the tool's purpose: 'Get the API reference and design rules for figma_write.' It is a specific verb+resource combination that distinguishes it from siblings by positioning it as the documentation/pre-requisite tool for figma_write, and it lists concrete content sections.

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 guidance is explicit and actionable: 'Call with no args first' then 'load specific sections as needed.' It also provides a hard rule: 'Always call figma_docs BEFORE any figma_write code.' This tells the agent exactly when and how to use the tool, including a workflow prerequisite.

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 must carry the full burden. It says 'READ' and lists extractable items, but does not explicitly disclose that it is read-only/non-destructive, mention authentication needs, or note limitations. The extensive operation descriptions in the schema are not part of the main description.

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 two sentences, front-loads the main purpose, and contains no unnecessary words. It is appropriately sized for a high-level tool summary.

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 (18 operations, 9 parameters) and the rich schema descriptions, the description provides a sufficient high-level overview. It covers major use cases ('understand an existing design', 'inspect what's on the canvas') while the schema fills in operation-level details. It does not mention some operations like search or viewport, but these are documented in the 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 the baseline is 3. The main description adds no parameter-specific meaning, but the schema's operation enum and parameter descriptions provide detailed semantics. The description itself does not compensate 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 'READ design data from Figma' with a specific verb and resource, and lists extractable content (node trees, colors, typography, spacing, screenshots). It differentiates from sibling tools like figma_write, which is the write counterpart.

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 usage context: 'Use to understand an existing design before generating code, or to inspect what's on the canvas.' It does not explicitly mention alternatives or when not to use, but the read/write distinction from siblings is 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. It discloses the behavior of aggregating current design data into a markdown block without modifying anything. The phrasing implies a read-only operation, and the usage note suggests it is safe and idempotent. It lacks explicit mention of permissions or side effects, but the described behavior 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 three sentences and front-loaded with the core function. It packs essential information—what it aggregates, the output format, and when to use it—without any filler or 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?

For a tool with one optional parameter and no output schema, the description gives a solid overview of the expected output (markdown block with tokens, styles, variables, components). It doesn't specify the exact markdown structure, but the enumerated contents and usage scenario provide sufficient context for an agent to invoke it 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% for the single optional sessionId parameter. The description adds minimal meaning beyond the schema, only mentioning that omitting it auto-selects the current file. Since the schema already explains the parameter, this score is the baseline.

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 generates a design system rule sheet by aggregating color tokens, typography, variables, and components. It uses a specific verb ('generate') and resource ('design system rule sheet'), and distinguishes itself from siblings by mentioning the exact content and the equivalent official tool name.

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 usage guidance: 'Call once at the start of a design-to-code session' and 'Re-run when the design system changes.' It also states the purpose—giving the AI full context—which clarifies when to use this tool over others that read or write specific parts of the 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 present, so the description carries the burden. It clearly states the tool performs a check, implying read-only behavior. However, it does not explicitly state side effects (none expected) or return format, which is a minor gap for a health-check 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 concise sentences, front-loaded with the action and followed by a clear directive. Every word earns its place; no redundancy or 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 zero-parameter health check with no output schema, the description adequately explains the tool's purpose and usage context. It does not describe the return value format, but 'check whether' implies a simple boolean. The explicit 'call first' instruction adds important operational context. Overall, sufficient for the tool's simplicity.

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 has 0 parameters, so the baseline is 4. The schema is empty and the description adds no parameter details, but that's acceptable since there are no inputs to document.

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 ('Check') and resource ('Figma plugin bridge') with a clear outcome ('is connected'). It distinguishes from sibling tools by establishing itself as a connectivity probe, not a data-reading or write 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 instructs 'Always call this first to confirm the plugin is running before any other tool,' which is a direct when-to-use directive. This clearly differentiates it from alternatives and sets a usage order without needing to mention 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 behavioral disclosure burden. It reveals that validation checks a specific list of design-system properties (fonts, typography roles, token colors, viewport, component dimensions, etc.) and that the tool does not fix errors itself—users/agents must fix and re-run. It does not explicitly state whether the tool is read-only or describe the exact output format, but the workflow strongly implies it returns errors.

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 primary action and purpose. The first sentence identifies the tool's job, the second lists concrete checks and the expected workflow. No wasted words or redundant restatements of schema fields.

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?

Moderate complexity (4 optional params, no output schema, no annotations) and the description covers the core purpose, checks, and usage context. It could be more explicit about the return value/error format and whether any side effects occur, but for a validation tool this is reasonably complete for an agent to select and invoke 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?

The input schema provides 100% coverage with clear parameter descriptions for nodeId, recipe, nodeName, and sessionId. The description adds minimal extra meaning beyond mentioning 'recipe-specific padding,' which slightly elaborates the recipe parameter. Since the schema already does the heavy lifting, a baseline score of 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 starts with a specific verb ('Validate') and a clear resource ('a generated Figma frame against the configured design-system bundle'). It distinguishes itself from siblings like figma_read, figma_write, and figma_status by focusing on design-system compliance validation, not reading/writing/status.

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 usage context: use after a frame is generated and before handing the design to the user, with an explicit 'fix every error and re-run' workflow. It does not explicitly name alternatives or exclusions, but the placement (post-generation, pre-handoff) makes the intended when-to-use fairly 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 provided, the description fully covers behavioral traits: mandatory pre-conditions, sandbox restrictions, async Promise-based methods, and specific side effects of misuse. It also enumerates supported operation categories, which is far beyond minimal disclosure.

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 lengthy and detailed, but appropriately so for a complex tool with many capabilities. It is front-loaded with the mandatory warning and organized into logical sections (operations, tokens, prototyping, etc.). Slightly verbose but every sentence carries useful 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?

Thoroughly covers the tool's complexity: operation types, asset handling, validation, design tokens, prototype interactions, sandbox limits, and required ordering. However, it does not describe return values or error handling, which would be helpful given the absence of an output schema. Otherwise highly 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 covers 100% of parameters, but description adds substantial meaning for `code` by providing operation examples, design token APIs, and expected JavaScript patterns. The `sessionId` parameter is not elaborated, but schema already handles it. The added detail raises value above baseline.

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 it executes JavaScript code to CREATE or MODIFY designs in Figma, with a specific verb and resource. Distinguishes itself from sibling tools like figma_read and figma_validate by focusing on write operations and listing concrete operation types.

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 mandates calling figma_docs before writing, and design_system_plan when configured, with warnings about consequences. Names figma_validate as a follow-up step, providing clear when-to-use context and differentiating from alternatives.

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