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

Annotations already mark the tool as idempotent and non-destructive. The description adds context about batch processing ('saves N-1 tool calls'), precedence of textNodeId over textNodeName, and the requirement for Phase 2, providing useful behavioral clues beyond the 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 highly concise, packing purpose, usage, and parameter details into a few sentences. It is front-loaded with the core action and efficiently adds context without 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?

Given the tool's simplicity and the presence of detailed schema annotations, the description covers essential aspects: usage flow, parameter selection, and efficiency benefits. It could mention error handling or limits, but the provided context is sufficient for an AI agent to use 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 description enriches understanding by explaining the overrides array structure, the distinction between textNodeName (by name) and textNodeId (exact match), and the role of configurationHints.textNodes. This adds significant value beyond the raw 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 overrides text on a component instance, with specific details on usage after figma_insert_component and differentiation between textNodeName and textNodeId. It distinguishes itself from sibling tools like figma_update_node by focusing on text overrides in bulk.

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 guidance on when to use the tool (after figma_insert_component, leveraging configurationHints.textNodes) and how to choose between textNodeName and textNodeId. It does not explicitly exclude other scenarios but offers sufficient context for appropriate use.

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 details behavioral traits: binds to DS variables, gates component-like names with confirmedNoComponent and primitiveOverrideReason, mentions GRID mode and its error behavior on unsupported Figma versions. Annotations are minimal, so description carries burden and does so effectively.

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 fairly dense but front-loads the main purpose. It lists key points without excessive verbosity. Could be slightly trimmed but overall 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 the tool's complexity (45 parameters, no output schema), the description covers high-level usage, constraints, and ties to other tools. Missing details about return value are acceptable without an output schema. Provides adequate 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 description adds significant value by highlighting key parameters (parentId, direction, layoutSizing, variable bindings, GRID mode), explaining naming conventions, and clarifying the gating mechanism. Goes well 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 creates an auto-layout container frame as a fallback when no DS component exists. It distinguishes from siblings by emphasizing it is a layout primitive and mentions checking mimic_map_components first.

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 to use this tool when no DS component exists, and to check mimic_map_components first. Also implies not to use when a component is available, and references phase 2+ for additional context.

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 are minimal (none set to true), but the description adds crucial behavioral details: the return includes unboundChildren requiring immediate follow-up, and failure to process them breaks DS compliance and light/dark mode. This goes beyond annotations and gives clear transparency.

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 concise (four sentences) and well-structured: purpose, use case, return behavior, required follow-up actions. Every sentence adds necessary information without 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 having no output schema, the description explains the output format (unboundChildren list). It covers required parameters, optional params with hints, and post-call steps. The DS compliance context is crucial for correct usage, making the description complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minimal extra param meaning beyond the schema, except for layoutSizingHorizontal where it provides a usage hint ('Use FILL for charts inside auto-layout containers'). This slight added value keeps the score at 3.

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 creates a node from an SVG string in Figma, specifies it is useful for icons and custom graphics, and naturally distinguishes it from sibling tools like figma_create_frame or figma_create_text which handle different input 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?

The description provides strong post-call instructions (must apply figma_update_node to unbound children for DS compliance), which guides the agent on proper usage. It does not explicitly contrast with alternatives but implies when this tool is appropriate via the use case mention.

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 it strips hardcoded line breaks (container width controls wrapping) and that nodes should be named after HTML roles. Annotations provide no behavioral info (all false), so the description adds these details. 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 concise (three sentences) and front-loaded with the core purpose. However, it mixes purpose, usage guidelines, and behavior in a single paragraph; a clearer structure could improve readability slightly.

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 (12 parameters, no output schema), the description provides sufficient context about what the tool does and its constraints. It does not explain return values, but that is acceptable since no output schema exists.

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, but the description adds context beyond the schema, such as mandatory conditions for textStyleId and fillVariable, and the naming convention. This adds value for parameter 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?

The description clearly states it creates a standalone text node bound to a DS text style and color variable. It specifies the verb 'creates' and the resource 'text node', and distinguishes it from the sibling tool figma_component_text.

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 this tool ('Use for text OUTSIDE components') and when not to ('text inside a component instance uses figma_component_text instead'). Also notes that textStyleId and fillVariable are mandatory when the DS has them.

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, adds that deletion is irreversible and never targets artboards, with verification guidance. 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?

Three focused sentences: action, constraint, guidance. No wasted words; well 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?

Complete for a single-param destructive tool: purpose, constraints, usage guidelines, behavioral traits covered. Output schema absent but irreversibility and verification suffice.

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%; description adds valuable constraint 'Must NOT be a top-level artboard' not present in schema description.

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 'Deletes a node from the Figma document.' Distinguishes from siblings by explicitly excluding artboards and suggesting alternative.

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 when-not-to-use (artboards), alternative action (create new artboard), and safety advice (verify with figma_inspect).

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, idempotentHint=true. The description adds the behavioral trait 'never blocked by phase gates,' which provides useful context beyond annotations. It also clarifies that parameters are conditional on the selected target. 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 dense but well-structured: it states purpose, key traits, usage guidance, then a parameter mapping. All sentences are relevant. It could be slightly more concise by separating the parameter listing, but overall it is efficient for the amount of 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?

Despite having 5 parameters and 100% schema coverage, the description does not explain the return format or structure for each target (e.g., what fields are returned for 'node' vs 'children'). With no output schema, the description should clarify what the caller can expect. The tool is complex (9 targets), so some gaps remain.

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 explicitly mapping each target value to its required parameters (e.g., 'nodeId (node/children/parent/text)', 'componentSetKey (variants)', 'sectionName (section)'). This helps the agent understand parameter dependencies beyond the enum labels.

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 'Reads Figma document state' and enumerates nine specific read targets (node, children, parent, etc.). The title annotation 'Inspect Figma document state' reinforces a specific verb+resource. This differentiates from sibling mutation tools like figma_create_frame or figma_update_node.

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 advises using the tool 'to verify state before/after edits, discover node IDs, or check what a component set supports.' It also notes 'Read-only, never blocked by phase gates,' which clarifies when it is safe to call. It does not explicitly mention when not to use it, but the read-only nature and sibling list imply it is not for modifications.

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 idempotentHint=true; the description adds 'Read-only' and clarifies it reads from a local cache. No contradictions, and the description supplements annotations appropriately.

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: main purpose first, then usage guidance, then parameter details. It is slightly verbose but every sentence serves a purpose. Could be tightened, but overall effective.

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 implicitly explains return values through examples (textStyleId, fillStyleId, variable path). It covers what an agent needs to know for selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and descriptions are already present, but the description adds value by explaining the context for each parameter (e.g., filter works only with fill_styles, category only with variables). This helps an agent understand conditional usage.

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 lists cached DS assets (text styles, fill styles, variables), with a specific verb ('Lists') and resource. It distinguishes from siblings like mimic_discover_ds and the figma_* tools that use these 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?

The description provides explicit context: 'Use to browse what mimic_discover_ds already cached before binding' and gives concrete examples of finding IDs for other tools. It lacks explicit 'when not to use' but the guidance 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 non-read-only, non-idempotent, non-destructive. The description adds that Phase 2 is required, and that fills are only for build-report visibility and never auto-replayed. 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 concise but packs multiple pieces of information without clear structural separation. It is efficient but could be more readable with bullet points or clearer grouping.

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 is present, but the description does not explain return values or error conditions. For a mutation tool, this is a gap. However, annotations cover some safety aspects, and the description includes important constraints (Phase 2, non-auto-replay).

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 the action-dependent requirement for componentKey and referencing external tool for slotName. This extra context justifies a 4.

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 fills or resets a SLOT-type component property on an existing instance, with two specific actions. It references Figma Slots and distinguishes from siblings by mentioning configurationHints.slotProperties from figma_insert_component.

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 fill vs reset, including the prerequisite to find slotName via figma_insert_component. Also notes that slot fills are recorded but never auto-replayed. However, it does not explicitly compare to other sibling tools or state when not to use this 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?

The description states the mutation nature (consistent with readOnlyHint=false) and specifies prerequisites like Phase 2 and DS validation for variable paths. It also notes that fill has fallback logic. No annotation contradiction; annotations are supported by the 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 well-structured: main purpose first, then ops in parentheses, then conditions via semicolons. It's moderately long but justified by the tool's complexity (30 params, 10 ops). No redundancy; 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 high complexity of the tool, the description is remarkably complete. It covers all operations, prerequisites, fallbacks, and even mentions the sibling tool for deletion. No output schema is present, so return values are not expected. The description leaves no critical 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?

All 30 parameters are already documented in the input schema (100% coverage), so the description's added value is primarily in grouping params by op and explaining their contextual use. This extra organization is helpful but not essential given the schema's quality.

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 mutates a Figma node or editor focus via an 'op' parameter. It enumerates all 10 operations with brief explanations, distinguishing this tool from sibling 'figma_delete_node' which is for removal. The verb 'mutates' and resource 'Figma node or UI focus' are specific and accurate.

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: which ops require Phase 2, which do not (select/page), and when to use alternative tool 'figma_delete_node' for removal. It also explains fallback behavior for fill operations. This helps the agent select the correct operation and avoid misuse.

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 and idempotentHint. The description adds valuable behavioral detail: the recursion, the types of violations checked (hardcoded colors/fonts, missing text style bindings), and that it runs against the current DS enforcement profile. 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?

Two concise sentences: first states purpose and scope, second gives usage timing and parameter hint. 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 compliance validation tool with an output schema (present but not shown), the description covers purpose, usage context, and parameter. It is complete enough for an agent to select 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% with nodeId description. The description adds context: 'nodeId (required, typically the artboard root),' which aids correct parameter usage.

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 recursively checks a node and children against DS enforcement profile, flagging specific violations (hardcoded colors/fonts, missing text style bindings). It distinguishes itself from siblings like figma_inspect or figma_list_ds by focusing on compliance validation.

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 guidance on when to use: 'during Phase 3/4 QA, especially at the 20-op build checkpoint, before generating the report.' However, it does not explicitly state when not to use or mention alternative tools.

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 modifies the node (consistent with readOnlyHint=false) and explains the mode-setting behavior for multiple collections. Annotations already provide idempotentHint=true and destructiveHint=false, which are not contradicted. The description adds context about the necessity and scope of changes.

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 very concise: three sentences followed by a param list. Every sentence adds essential information: purpose, necessity, default behavior, and parameter details. No redundant phrasing.

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 simple setter with no output schema, the description adequately covers the operation, necessity, and parameter logic. It could mention return value or confirmation, but the context is sufficient 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?

With 100% schema coverage, the description adds value by clarifying typical usage for nodeId ('typically the artboard'), explicit values for modeIndex (0=light, 1=dark), and the effect of omitting collectionName. This exceeds 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 the verb 'Sets' and the resource 'variable mode on a node', with a specific use case ('required on every new artboard'). This distinguishes it from sibling tools like figma_update_node or figma_create_frame.

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 ('required on every new artboard') and what happens if not used ('DS variables render as black'). It also covers the default behavior (all collections) and how to target a single collection. It does not explicitly list when not to use 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 declare readOnlyHint and idempotentHint. Description adds detail on exactly what the knowledge store contains and how the format parameter affects output ('structured data' vs 'DESIGN.md markdown string'). 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 front-loading the main purpose, followed by parameter detail. No unnecessary words; every sentence is informative.

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 return contents (named categories) and the alternative format outcome. Tool is simple (1 optional param), so description is 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%, baseline 3. Description adds value by explaining the purpose of each enum value: 'json' returns structured data, 'design_md' returns a markdown string for documentation/handoff. This goes beyond the schema description.

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 the knowledge store and enumerates its contents (component recipes, layout data, DS gaps, rules, meta stats). It distinguishes from sibling tools like mimic_ai_knowledge_write and provides a usage recommendation ('Call at the start of a session').

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 advises when to call ('at the start of a session') and why (to see what has been learned). Does not list exclusions or alternatives, but the sibling context (e.g., write tool) implies 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?

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that the tool lets Mimic learn across builds, but does not disclose potential failures, permissions, or side effects beyond what annotations cover. With annotations providing the safety profile, the description adds moderate 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 concise with two sentences and a brief params summary. It front-loads the purpose and usage guidance without redundancy. 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 there is no output schema, the description is complete. It explains the tool's purpose, usage guidelines, and parameter details. Annotations provide idempotence and non-destructive hints, making the description sufficient for an agent to invoke 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% with descriptions for all parameters. The description adds extra meaning for the 'type' parameter by providing use cases and examples (e.g., 'rule' for design rules), which goes beyond the schema enum list. The 'id' and 'data' parameters are clear from schema but not further elaborated.

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 saves knowledge entries (component recipe, layout pattern, DS gap, or design rule) to a persistent store. It uses a specific verb (saves) and resource (knowledge store), and distinguishes itself from the sibling mimic_ai_knowledge_read 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 provides explicit guidance on when to use the 'rule' type (user correcting build behavior in a generalizable way) and notes that other types are usually written automatically. It does not explicitly state when not to use the tool, but the guidance is clear enough.

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 readOnlyHint=false, idempotentHint=false, destructiveHint=false. Description clarifies it creates new nodes, but doesn't specify if it overwrites or what happens on conflict. It also adds useful restrictions like color palette: 'never Brand/Success/Warning/Error'. 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?

Description is front-loaded with purpose and benefits. It is fairly concise, though includes a slightly cryptic 'Phase 2+' at the end. Overall 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, description does not mention what the tool returns (e.g., node ID). The 'Phase 2+' note is confusing. For a complex tool with 12 parameters, it mostly covers inputs but lacks return 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%, so baseline 3. Description adds value by specifying data shapes per chart type (e.g., bar: [{label, value}]) and color restrictions beyond schema. Justifies a 4.

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 builds an entire chart in one call, enumerating components (container, visualization, labels, grid, legend) and chart types (bar, line, donut, radar). It distinguishes itself from hand-building and from the sibling tool mimic_compute_chart.

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 usage guidance: 'Use for ANY HTML chart instead of hand-building; reduces 30-50 tool calls to 1.' Also tells when to use an alternative: 'Use mimic_compute_chart for geometry-only.'

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 only set readOnlyHint=false, so the description carries the burden of behavioral disclosure. It explains the bulk creation nature and mentions a prerequisite check. It could further detail side effects (e.g., whether existing nodes are modified), but the provided context is solid and does not contradict 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 but front-loads the main idea and key benefits. It is appropriately sized given the complexity, though structured bullet points could improve scanability. Every sentence adds value, with 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?

Considering the tool's complexity (9 parameters, nested objects, no output schema), the description covers the purpose, key parameters, and a prerequisite. It mentions returning creation guidance if DS components are missing. It lacks a description of the return value, but given the complexity, the description is quite complete overall.

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 detailed descriptions for all 9 parameters. The description adds value by explaining key usage patterns (e.g., 'text|supporting' syntax for rows, cellHeight for alignment) and providing examples (cellVariants for badge colors). This goes beyond the schema, justifying a 4.

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 'Bulk table builder' that creates an entire data table in one call, listing specific components (column frames, DS Table header cell, Table cell, variants, text, row height). It explicitly distinguishes from cell-by-cell insertion, making the purpose unambiguous and distinct 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?

The description provides explicit when-to-use guidance ('Use for ANY HTML data table instead of cell-by-cell insertion') and highlights a key prerequisite ('Requires table cell components in the DS'). It also notes the benefit of reducing tool calls from 200+ to 1, giving clear context for selection.

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 info, but the description adds extensive behavioral context: two-step process, caching, verification, blocking, community library handling, phases, and response types (communityVariablesRequired). 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 a single dense paragraph that could benefit from structuring (e.g., steps, bullet points). It front-loads the purpose but is longer than necessary. Adequate but not optimal.

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 (8 parameters, nested objects, two-step process, output schema exists), the description is fairly complete. It explains phases, blocking, community handling, and caching. The output schema covers return values, so missing details are acceptable.

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% (baseline 3). The description adds value by explaining parameter usage context (e.g., communitySearchResults required after initial discovery, externalVariables when communityVariablesRequired). This slightly exceeds 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 'Complete DS discovery in two steps' and explains the entire process, including phases and blocking. It distinguishes from sibling tools like mimic_map_components and build tools by specifying this discovers the design system and blocks build tools until completion.

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 on when to call (step 1 with fileKey, step 2 with communitySearchResults). Provides conditional guidance (e.g., for communityVariablesRequired, fetch via Figma MCP and pass as externalVariables). Also clarifies that build tools are blocked until step 2 completes.

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 only provide readOnlyHint=false and idempotentHint=false. The description adds significant behavioral context: caching mechanism, gap confirmation, and the search loop completion behavior. 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 around 100 words, front-loads the core purpose, and is divided into clear sentences. Every sentence adds value, and there is no redundancy or unnecessary 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 tool's complexity (2 params, output schema exists), the description covers purpose, workflow position, caching behavior, and conditional usage. It does not cover error handling, but with the existing output schema, the description is sufficiently complete for an AI agent.

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 valuable semantic guidance for both parameters: for elementTypes it specifies 'all section-level + control element types', and for librarySearchResults it explains the search loop and filtering behavior, going beyond the schema's type 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 maps HTML element types to DS component keys, providing specific examples (button, input, etc.) and distinguishes itself from sibling tools like mimic_discover_ds by specifying its workflow position.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on when to call (after mimic_discover_ds, before figma_insert_component) and how to use it differently depending on FIGMA_TOKEN presence. It does not list alternatives or when not to use, but the conditional instructions are very 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 indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context beyond annotations: it clears build-interrupt state after a plugin reconnect and warns if a completed build is missing its mandatory report. These side effects are disclosed and consistent 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 dense but well-structured, starting with the imperative instruction and listing all return fields and side effects. Every sentence adds value. Slightly verbose but justified by the complexity of the status 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?

Given the tool returns a complex status and a hint for next steps, and that an output schema exists (context signals indicate true), the description covers purpose, usage, side effects, and parameter constraints completely. No gaps remain for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters (schema coverage 100%). The description explicitly states 'No params — call with no arguments,' adding clarity beyond the empty schema. Baseline is 4 for no-parameter tools, and this description fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool returns Figma plugin connection status, build phase, enforcement profile, cached DS counts, knowledge store summary, and a contextual hint for next call. It distinguishes itself from siblings by explicitly instructing to start every session here, making purpose and scope clear.

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 'START EVERY SESSION HERE,' providing clear when-to-use guidance. It also explains that the tool returns a hint telling the agent what to call next, guiding sequential behavior. No exclusions needed given its role as the first tool.

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