basecoat-ui

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

Annotations already declare idempotentHint=true and readOnlyHint=false, and the description meaningfully extends that: replay returns the original receipt, committed mutations always acknowledge success, oversized optional fields may be omitted with truncated:true, and it does not touch source files. This is substantive behavioral context 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?

Four tight sentences that are front-loaded with the atomic-apply statement and follow with replay, acknowledgment/truncation, and scope boundary. No filler; each sentence carries distinct 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?

With no output schema, the description compensates by describing the return behavior (receipt on replay, success acknowledgment, truncated:true), and it covers concurrency and idempotency for a mutating tool. The omission is any explanation of the operation kinds themselves, though the schema's oneOf branches carry that.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: operationId is positioned as a replay/idempotency key and expectedRevision as the concurrency guard, tying the parameters to their operational contract.

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

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

Specific verb+resource: 'Apply one atomic list of design graph operations' clearly names both the action and the target, and the closing 'Does not write application source files' carves out scope. It does not name a sibling alternative, but the graph-mutation domain is 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?

Idempotency and concurrency requirements are explained ('Replay with the same operationId', 'with expectedRevision'), which imply the calling context, but there is no explicit when-to-use or when-not-to-use guidance relative to validate_design or the other design 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and closed-world, so the safety profile is fully covered structurally. The description adds useful behavioral detail about the payload (pre-configured FSM state variants plus dependencies), but says nothing about return format, size, or limits.

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 stage tag and the core action, with no wasted clauses. It is appropriately sized for the tool, though the bracketed stage marker is meta-scaffolding rather than tool-specific content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does carry the burden of explaining the return value, and it does so ('copy-pasteable markup with state variants and dependencies'). Combined with annotations covering safety and a 100%-covered schema, the definition is nearly complete, with only the absence of sibling disambiguation as a gap.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema, making 3 the baseline. The description echoes the state variants and dependencies but adds no syntax or format guidance beyond what the schema provides, and does not clarify the four alias 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 states a specific verb and resource ('Retrieve copy-pasteable Basecoat component markup') and adds scope (57 components, FSM state variants, dependencies). However, it never distinguishes itself from lookalike siblings such as get_component_html or get_component_syntax, so an agent still has to guess which retrieval tool to pick.

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 '[STAGE 3: SYNTAX & STACKS]' label and 'Next step: Call basecoat_quality_inspector' give workflow context, which implies when this tool fits. But there is no explicit when-not guidance and no comparison to the sibling retrieval tools that appear to do overlapping work.

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=true and destructiveHint=false, establishing this as a safe, repeatable composition step with no persistence. The description adds value beyond that by naming the produced artifact (a full shell architecture with hydrated slots), the downstream verification step, and the optical density concept; it still says nothing about the returned payload, but with annotations covering the safety profile and no output schema, this is a solid 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?

Two sentences, both earning their place: the first front-loads the stage and the core action, the second routes to the next tool. The long parenthetical stack enumerations and bracket tag make it dense, but they carry real routing information rather than 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 10-parameter, zero-required composition tool with full schema coverage and no output schema, the description supplies the missing conceptual layer: what a 'shell + stacks' composition is and how it is validated afterward. The omission of return-value/pagination-style detail is acceptable precisely because no output schema exists to be redundant with, though a hint about the returned artifact would close the gap.

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

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

Schema description coverage is 100%, so every parameter (including the alias cluster id/name/shell/componentId, the stacks array, and density) is already documented with defaults and enums in the schema. The description's examples overlap heavily with the schema's own examples for `stacks`, adding little new syntax or format meaning. Baseline 3 applies when the schema carries the load.

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 names a specific verb+resource ('Assemble full shell architectures', 'hydrate pre-configured component stacks into slots') and enumerates the concrete artifacts involved (sidebar-01..16, topbar-shell, kpi-4-col-delta, data-table-full-crud). It is clearly distinguishable from siblings like basecoat_component_syntax or basecoat_quality_inspector, including by nominating one of them as the follow-up stage.

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 '[STAGE 3: SYNTAX & STACKS]' prefix and 'Next step: Call basecoat_quality_inspector to verify markup compliance' give explicit workflow sequencing, so the agent knows where this fits. However, it never states when NOT to use it or which sibling covers the adjacent stages (e.g., basecoat_page_architect), leaving the only exclusion to inference.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful context that this is a read-only advisory stage in a multi-stage pipeline, but discloses nothing further about what it returns or any limits.

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, stage tag front-loaded, no padding. It is efficient, though the topic enumeration largely duplicates the topic enum and could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 100% schema coverage and full annotations, the structured data covers inputs and safety, and there is no output schema to explain. What remains missing is disambiguation from the crowded sibling set (get_rhythm_rules, get_design_rules, basecoat_page_architect), which an agent in this pipeline genuinely needs.

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 8 well-documented parameters and five enums, so the schema carries parameter meaning entirely. The description's topic list loosely echoes the topic enum but adds no syntax, defaults, or interaction semantics 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 states it surfaces Kanso minimalism and design intelligence across enumerated topics (typography ladders, spacing rhythm, whitespace density, contrast ratios, style packs, elevation), which aligns with the topic enum. However, the verb 'Surface' is abstract and the phrasing is marketing-flavored rather than a concrete verb+resource. It does not distinguish itself from close siblings like get_rhythm_rules, get_design_rules, or get_creative_direction.

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 '[STAGE 2: RULES & RHYTHM]' tag plus 'Next step: Call basecoat_compose_stack or basecoat_component_syntax' gives genuine workflow positioning. But it never states when to choose this tool over alternatives such as get_rhythm_rules or get_design_rules, so usage is only implied by pipeline order.

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 and non-destructive behavior, so the safety profile is covered. The description adds genuine behavioral value by specifying exactly what comes back (markup, tokens, layout footprint, per-framework mount code) and that theme overrides are optional.

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 dense sentences with the stage tag and core payload front-loaded, ending with a next-step pointer. Every clause (tokens, layout, mount code) conveys content, though the enumeration is slightly heavy.

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 must describe returns, and it does so thoroughly (markup, theme tokens, layout footprint, client options, framework mount code). Combined with 100% schema coverage and clear pipeline positioning, only auth/limits context is absent, which is minor for a read-only tool.

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

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

Schema coverage is 100%, so the schema carries the parameter burden including aliases and enum meanings. The description mentions 'chart blueprint ID or category' and per-framework mount code, which lightly maps to chartId and framework, but adds no syntax beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb ('Retrieve') and resource ('complete chart markup, CSS theme tokens, layout footprint, client options, and framework mount code') for a chart blueprint ID or category. The enumerated outputs make it distinguishable from basecoat_list_charts, which only lists blueprints rather than fetching their full markup.

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 '[STAGE 3: SYNTAX & STACKS]' tag and 'Next step: Call basecoat_quality_inspector' route the agent through the pipeline and imply this runs after selection. It doesn't explicitly state when-not-to-use or name basecoat_list_charts as the prerequisite, 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered by structured data. The description only adds the catalog size ('50+') and the stage label; it does not disclose return shape, pagination, or match behavior. Adequate but thin on 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?

Two front-loaded sentences with a clear action statement followed by the next-step directive; nothing is wasted. The '[STAGE 3: SYNTAX & STACKS]' prefix is moderately useful workflow scaffolding but borders on meta-clutter.

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 read-only listing tool with full param coverage and safety annotations, the definition supplies the essential action, filters, and next step. It omits what a returned 'blueprint' record contains, but the routing to get_chart_blueprint largely compensates.

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 all six parameters (including the id/componentId aliases and query/search aliases) are already documented in the schema. The description restates the category enum and mentions keyword search but adds no syntax, format, or precedence rules beyond the schema, so baseline 3 applies.

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

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

States a specific verb pair ('List and filter') and a concrete resource ('50+ Basecoat ApexCharts and SVG data visualization blueprints') with the filter axes named (category, keyword). It is clearly distinguished from the sibling basecoat_get_chart_blueprint, which it explicitly frames as the follow-up step.

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

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

Gives explicit workflow routing: 'Next step: Call basecoat_get_chart_blueprint with the selected chart ID,' so the agent knows what comes after this tool. It does not state when NOT to use it or contrast it with search_components/list_blocks, so no exclusion guidance, but the routing 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing what is actually returned — scaffolds containing explicit slot markers, grid structures, and responsive containers — which is important behavioral context given there is no output schema. It stops short of describing pagination, size limits, or failure behavior when an id/recipe is not found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the stage label and the core action, followed by the downstream call chain. No filler, though the long parenthetical enumeration of scaffold types is slightly list-heavy and the 'Next step' sentence is compressed enough that its conditional logic is implicit rather than ordered.

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-required-parameter, eight-parameter retrieval tool with no output schema, the description succeeds at conveying both what comes back (slot-marked scaffolds) and where it sits in the multi-step workflow. The main residual gap is that the alias relationship among id/name/block/intent/recipe/componentId is left entirely to the schema, so an agent has no description-level guidance on precedence when several are supplied.

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 all eight parameters are already documented in the schema, including the enums for density and environment. The description supplies concrete example values (workspace-dashboard, auth-split-flow, sidebar-07) that loosely mirror the intent/recipe/block parameters, but adds no meaningful semantics beyond what the schema already states. Baseline 3 applies.

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

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

States a specific verb pair (search and retrieve) plus the exact resource (complete layout scaffolds) and enumerates concrete artifact types (Workspace Dashboard, Auth Split-Screen, Data Table Detail, etc.). The '[STAGE 1: ARCHITECT]' tag and the emphasis on slot markers/grid structures/responsive containers make it clearly distinguishable from sibling retrieval tools like search_macro_blocks or get_component_html.

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 positions itself as the first stage and prescribes the exact follow-up chain: basecoat_rules_enforcer and basecoat_creative_director, then basecoat_compose_stack or basecoat_component_syntax. This is strong sequencing guidance, but it never states when NOT to use it or how it differs from adjacent retrieval siblings such as search_macro_blocks, get_macro_block, or get_page_architect.

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, destructiveHint=false, and openWorldHint=false, so the safety and repeatability profile is clear. The description adds the stage positioning and the report contents, which is useful context beyond the annotations, but it does not mention defaults, limits (e.g., the 262144 maxLength), or how the FSM/density checks behave.

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 stage tag and the verb/resource. It is efficient, though the bracketed stage prefix and the 'Final quality gate' clause are somewhat redundant framing.

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 10-parameter, zero-required tool with no output schema, the description explains the report sections but not the return structure, the meaning of a partial/omitted input, or how the many alias parameters (code/html/markup) should be chosen. It is adequate but leaves real gaps for a tool this broad.

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 every parameter is already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 the correct 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?

Names a specific verb (Audit) and resource (HTML/Astro markup) and states the output shape (Score 0-100, Syntax Violations, Accessibility/ARIA omissions, Auto-Fix). It positions itself as the 'Final quality gate' but does not distinguish itself from the very close siblings validate_markup and validate_composition.

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?

There is no when-to-use guidance or routing to alternatives. Given siblings like validate_markup, validate_composition, and validate_design, the agent has no explicit signal for when this Stage 4 gate is the right call versus those validators.

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, destructiveHint=false, and openWorldHint=false, so safety and repeatability are covered structurally. The description adds that results are 'indexed technical constraints' spanning four categories, but says nothing about pagination, result volume, or how auditing output is shaped.

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 with the stage marker front-loaded and no filler; every clause carries information about scope or next action. The bracketed stage tag is slightly meta but useful for pipeline ordering.

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 an 8-parameter, no-output-schema retrieval/audit tool, the description covers what is retrieved and the downstream step, and the schema covers each parameter. It still omits how the two modes (id/query lookup vs code/html auditing) relate and when to supply which, leaving a gap an agent must guess at.

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% across all 8 parameters, including enum explanations for category and environment, so the schema does the heavy lifting. The description adds no parameter-level meaning at all, which is the baseline 3 when structured fields are already complete.

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

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

States a specific verb and resource (retrieve indexed technical implementation constraints) and enumerates the four covered domains: Tailwind v4 syntax, FSM data-state contracts, CSS variable tokens, and semantic HTML landmarks. It is clear what it returns, though it does not directly distinguish itself from near-name siblings like get_rhythm_rules, get_design_rules, or enforce_rules.

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 [STAGE 2] tag and the trailing 'Next step: Call basecoat_creative_director or basecoat_component_syntax' place the tool in a workflow and route the agent onward. However, there is no guidance on when to choose this over the overlapping rules/rhythm siblings, so usage is implied rather than specified.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond that: it never says whether generated artifacts are returned as text or written to disk, nor anything about repeat-run behavior or side effects. Adequate, but not additive.

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 action and its outputs are front-loaded, followed by the routing sentence. The first sentence is densely packed with long enumerations, but virtually nothing is wasted and the ordering of information is useful.

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 read-only generator with no output schema, the description usefully enumerates the artifact types produced so the agent knows what comes back. Minor gaps remain about output shape (single blob vs. multiple files) and whether anything persists, but the core call decision is fully supported.

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 merely repeats the framework and style-pack enumerations already in the schema. It adds no meaning about the alias parameters (id, name, componentId) or how environment relates to framework, so the baseline 3 applies.

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

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

The description names a specific verb and resource set: generating Tailwind v4 @import statements, OKLCH tokens, @theme inline blocks, and bootstrap scripts. It enumerates the exact framework and style-pack domains and labels itself 'STAGE 1: ARCHITECT', which separates it from sibling stages like basecoat_compose_stack and basecoat_page_architect.

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 stage label plus an explicit 'Next step: Call basecoat_compose_stack or basecoat_page_architect' gives clear sequencing and routing. It does not state when NOT to use it or what prerequisites exist (existing config, project state), so it stops short of full when/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?

Annotations already cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds genuinely new behavior beyond them: it pins and hash-verifies the packaged macro registry, and notes that oversized optional receipt fields may be omitted via truncated:true after commit. These are real operational traits, not restatements of 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 core action is front-loaded in the first sentence and the sentences are dense and mostly earn their place. The trailing truncated:true/receipt-fields sentence is somewhat opaque and references concepts not present in the input schema, slightly diluting clarity.

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 4-param creation tool with nested objects and no output schema, the description covers the mutation behavior, idempotency, and persistence well, but never indicates what the call returns (e.g. the created session or registry pin), which an agent would need in 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 the schema already documents all four parameters well. The description lists the parameters and lightly clarifies profile ("alias or ref"), but adds little syntax or semantics beyond the schema's own descriptions. 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 opens with a specific verb+resource ("Create a persistent design session") and adds a scope detail ("under the host project root"), clearly separating it from siblings like apply_design_patch or validate_design. It is clear, though it never names a sibling explicitly for disambiguation.

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

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

Usage is implied rather than stated: an agent infers this is the entry point that starts a session before patching/validating. "Idempotent for the same operationId" hints at safe re-invocation, but there is no explicit when-to-use/when-not guidance or named alternative.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false, destructiveHint=false). The description adds the alias equivalence, which is useful, but discloses no behavior beyond that – no statement of what is produced, whether anything is persisted, or any constraints. It does not contradict the annotations, so no reduction applies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the stage tag and the alias relationship, with zero filler. Every clause carries 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?

With 10 parameters, no output schema, and a generate/assemble operation, the description should say what the tool returns (markup, file paths, a composition result). It does not, leaving the agent unable to anticipate output shape, though the schema does cover all inputs.

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% and the schema itself documents every parameter richly (alias mapping, defaults, enum values, examples). The description contributes no parameter-level meaning beyond what the schema already provides, so the baseline 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?

States a concrete verb pair ("assemble" / "hydrate") and named resources ("shell architectures", "pre-configured component stacks into slots"). Critically, it declares itself an alias of basecoat_compose_stack, so an agent can immediately tell it is a duplicate entry point rather than a distinct capability.

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 "[STAGE 3: SYNTAX & STACKS]" tag gives pipeline context, but there is no explicit when-to-use/when-not guidance and no statement of how this alias differs in usage from basecoat_compose_stack. Usage is only implied by the stage label.

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=false, destructiveHint=false, so the safety profile is covered. The description adds 'indexed' (implying a pre-built corpus) but does not disclose return behavior, whether it audits the passed code or just returns rules, or how aliases interplay.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with a stage prefix — no waste. It is front-loaded, though the stage tag is metadata rather than useful description.

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 an 8-parameter tool with no output schema, the description does not explain what is returned, how the code/html audit mode works versus query mode, or how strictness is applied. The annotations cover safety but the description is too thin to guide correct invocation.

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

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

Schema description coverage is 100%, so every parameter is documented in the schema itself. The description adds no syntax, format, or precedence detail (e.g., which of id/name/componentId/query win when combined). Baseline 3 when the schema does the work.

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

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

States a verb+resource ('retrieve indexed technical implementation constraints'), but the framing as an 'alias of basecoat_rules_enforcer' plus a stage tag does most of the disambiguating work. It doesn't say what these constraints look like or how it differs from sibling get_design_rules/get_rhythm_rules beyond the parent 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?

No when-to-use guidance, no when-not-to-use, and no mention of alternatives like get_design_rules or get_rhythm_rules. The '[STAGE 2: RULES & RHYTHM]' tag implies it belongs in a pipeline stage but doesn't explain call conditions or prerequisites.

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 cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world). The description usefully adds that this is an alias of another tool and enumerates the return payload (markup, CSS theme tokens, client options) — valuable given there is no output schema — but it says nothing about whether the alias is functionally identical to the basecoat tool or about defaults/resolution 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?

Two short sentences with no filler, and the action/return value is front-loaded after a compact stage tag. The bracketed stage prefix is opaque internal jargon that consumes space without informing the agent, keeping it just short of a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the necessary work of naming the return payload, and the thorough input schema covers all 8 optional parameters. The remaining gap is that it never clarifies the alias's relationship to or difference from basecoat_get_chart_blueprint, which is the main ambiguity an agent would face.

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%, including detailed alias documentation for id/name/componentId and enum values, so the baseline is 3. The description only obliquely references parameters via 'CSS theme tokens' (themeTokens) and 'client options' and adds no syntax, defaulting, or precedence rules beyond what the schema already states.

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

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

States a specific verb and resource — 'Retrieve complete chart markup, CSS theme tokens, and client options' — and identifies itself as an alias of basecoat_get_chart_blueprint, which tells the agent exactly which underlying capability it maps to. It does not, however, distinguish itself from other chart-adjacent siblings such as list_charts or get_component_html beyond the alias note.

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 only usage signal is the '[STAGE 3: SYNTAX & STACKS]' prefix and the alias declaration, which imply placement in a workflow but never state when to call this instead of basecoat_get_chart_blueprint or when a chart must first be listed. No when-to-use, when-not-to-use, or alternative routing is given.

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/idempotent/non-destructive/false openWorld, so the safety profile is covered. The description still adds genuine behavioral context: the special empty-argument mode returning a catalog index, and the intended workflow position after integration.

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, front-loaded with purpose, then valid IDs, then the empty-call behavior and next step. Efficient, though the 'Astro or HTML' qualifier adds a slightly misleading constraint that costs a point.

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 read-only, no-required-parameter tool with no output schema, the description covers what is returned, the empty-argument edge case, and the follow-on tools. It is close to complete; only the relationship to get_component_html and the framework coverage discrepancy are unaddressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add the universe of valid ids (57 Basecoat components) and the {} semantics, but it says templates are 'for Astro or HTML' while the environment enum also offers react, vue and svelte — a mild mismatch that could steer the agent away from valid options.

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

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

States a specific verb and resource (get one minimal component template plus dependencies and composition tips), and the word 'one' scopes it against the list-returning search_components. It never names a sibling explicitly, so the agent must infer the boundary from the ID list rather than being told.

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

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

Gives concrete usage context: an empty {} call returns the catalog index, and it prescribes the follow-up step (validate_composition or basecoat_quality_inspector after integrating markup). It does not say when to prefer get_component_html or another sibling over this tool, so the alternatives side is missing.

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, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context — the empty-argument catalog fallback and the valid-ID universe — but says nothing about output size, caching, or template resolution 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?

Two tight sentences with the return value front-loaded and the follow-up action last. No filler, though the "Valid IDs" fragment reads slightly like a note rather than prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the necessary work by naming what comes back (HTML markup plus dependencies, or the catalog index). It is adequate for a zero-required-parameter fetch tool, missing only return-shape specifics.

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 id/name/componentId/environment are fully documented in the schema. The description contributes only the no-argument catalog case and the count of valid IDs, which is marginal value over structured fields.

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

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

States a specific verb and resource ("Fetch HTML markup template and dependencies for a Basecoat component") and adds scope detail (57 valid IDs, catalog index on empty call). It doesn't explicitly distinguish itself from the sibling get_component_details, so the agent must infer the difference.

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

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

Gives concrete routing guidance: empty-object calls return the top-level catalog index, and it names the follow-up tools (validate_composition, basecoat_quality_inspector). It stops short of stating when NOT to use this versus get_component_details.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds that output is 'copy-pasteable' markup with FSM state variants bound in, which is useful context, but says nothing about permissions, limits, or fallback 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?

Two short, front-loaded sentences that waste no words. The bracketed stage tag is slightly noisy but does front-load workflow placement.

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 read-only single-resource retrieval tool with no output schema and fully documented parameters, the description covers purpose, source of truth, and output nature. Only the relationship to sibling retrieval tools remains unstated.

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% and all 9 parameters, including 4 enums, are documented in the schema itself. The description adds no syntax, default, or interaction guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (Basecoat component markup) plus the key qualifier that it is an alias of basecoat_component_syntax. It also names the scope ('with FSM state variants'), which distinguishes it from a plain markup lookup, though it never contrasts itself with siblings like get_component_html or get_component_details.

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 '[STAGE 3: SYNTAX & STACKS]' prefix implies where this fits in a workflow, and the alias note implies equivalence with basecoat_component_syntax, but there is no explicit when-to-use vs when-to-use-an-alternative guidance against the many sibling retrieval 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the stage/aliasing context but discloses nothing about the nature of the output or its relationship to the aliased tool, so it only marginally exceeds the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the stage marker front-loaded and no filler. It is efficiently structured, though the cryptic phrasing sacrifices some clarity for brevity.

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 an eight-parameter tool with five enums and no output schema, the description is too thin. It does not characterize what creative direction output looks like or how the many optional selector parameters shape the result, leaving the agent to infer behavior entirely from the schema and the unnamed alias target.

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 five of eight parameters having detailed enum descriptions, so the schema fully carries parameter meaning. The description contributes no additional parameter context, making the baseline 3 appropriate.

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

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

The description names an alias target ('Alias of basecoat_creative_director') and a workflow stage ('[STAGE 2: RULES & RHYTHM]'), which helps orient the agent. However, 'Surface Kanso minimalism and Basecoat design intelligence' is poetic rather than a concrete verb+resource statement, so it is unclear what this tool actually retrieves or returns.

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?

There is no when-to-use vs when-not guidance. The alias note implies equivalence to basecoat_creative_director, but the description never says whether to prefer this over that sibling, get_design_context, or get_rhythm_rules. The stage tag hints at workflow ordering but does not specify selection conditions.

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 establish readOnly, idempotent, and non-destructive, so the bar is lower. The description still adds real value beyond them with the revision-pinning contract ("Pin revision on first read; continuations must match"), a stateful constraint not expressed anywhere in annotations or schema.

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 dense sentences with no padding, front-loaded on the enumerated views. It is efficient but slightly cryptic — the second sentence's contract is terse enough to require re-reading, which keeps it just short of ideal.

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 10-parameter read tool with no output schema, the definition covers the view set and revision semantics but says nothing about cursor/pagination behavior or how the views differ in payload. The individual schema descriptions carry most of the parameter burden, so it is adequate but leaves notable 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%, so the baseline is 3 and the schema already documents all ten parameters including the view enum and designId requirement. The description nonetheless adds the non-schema revision-continuation rule and notes the designId exemption for the sessions view, giving marginal extra meaning.

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

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

States a specific verb ("Read") plus the resource (a focused design view) and enumerates the seven valid views, so the agent knows exactly what is retrieved. It also carves out scope against a sibling with "Does not create sessions," implicitly separating it from begin_design, though it doesn't name that sibling explicitly.

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

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

It gives conditional guidance ("sessions (no designId)") and a revision-continuation rule, which is more than nothing. However, it never states when to prefer one view over another or names the alternative tool an agent should pick for session creation, so usage is implied rather than spelled out.

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, and destructiveHint=false, so the safety profile is covered structurally. The description adds one behavioral detail beyond that - the empty-argument call returns the catalog index - which is helpful but thin; return format, filtering behavior, and result shape are not described.

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 substantive purpose and followed by the empty-call behavior. No filler or redundancy; slightly terse rather than wasteful.

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 read-only retrieval tool with fully documented parameters and no output schema, the description is nearly complete, and the empty-call index behavior covers the main discovery path. A brief note on return shape would be the only remaining gap, and it is minor absent 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% across all 10 parameters, so the schema already documents each field including the two enums. The description adds no per-parameter meaning (e.g., how query vs name vs id differ, or how aliases resolve) beyond what the schema states, so this is the baseline case.

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

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

States a specific verb (Retrieve) and resource (technical implementation constraints), then enumerates the covered domains: Tailwind CSS v4 syntax, FSM data-state contracts, CSS variables, and HTML landmarks. This is clear, though it does not explicitly distinguish itself from overlapping siblings like get_rhythm_rules, get_fsm_recipe, or get_design_context, which appear to cover adjacent ground.

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 one usage hint given is genuinely useful: calling with {} returns the top-level catalog index, which implies a discovery workflow. However, it names no alternatives and gives no when-not guidance relative to the numerous sibling rule/context tools, leaving the agent to infer routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds one genuinely non-redundant fact: the result is structural metadata rather than runnable code, which informs interpretation. It says nothing about pagination behavior or result shape, so it exceeds the annotation baseline only modestly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the operation and its scope front-loaded and the metadata caveat immediately after. Nothing could be cut without losing 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?

For a read-only tool with 100% schema coverage and no output schema, the description covers the essential floor. However, with 8 parameters and four separate string fields ('id', 'name', 'recipe', 'componentId') all described as recipe identifier aliases, a sentence clarifying which to supply and how pagination works would meaningfully reduce miscalls.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters. The description re-lists the section values that the schema enum already defines and adds no format or interaction detail (e.g., how `recipe`, `id`, `name`, and `componentId` alias one another). Baseline 3 is appropriate when 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 uses a specific verb ("Read") and enumerates the exact resource slice ("finite FSM states, events, guards, actions, or transitions"), which maps directly to the `section` enum. It is clear what the tool returns, but it never distinguishes itself from the many sibling read tools (get_component_details, get_macro_block, get_design_rules) by naming when this one applies instead.

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?

There is no when-to-use guidance, no precondition, and no alternative named. The second sentence ("Recipes are structural metadata, not executable runtime code") is a useful scoping caveat but is not routing guidance. An agent must infer from the name alone that this is the FSM-metadata reader.

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/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: pagination requires cursor iteration to completion, and designId pins alias resolution to a session registry. It stops short of describing return shape or the alias-resolution rules without designId.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with zero filler, front-loading the core action and resource before the pagination and session nuances. Nothing is repeated from the schema and every sentence carries distinct 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?

There is no output schema, so the description must carry return expectations, and it does by naming the sections and the cursor-following requirement. It does not clarify that id/name/componentId are mutually exclusive aliases of idOrRef, but the schema attests to that, leaving only a minor gap for an 8-param, 0-required 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?

With 100% schema coverage the baseline is 3, but the description adds meaning beyond the schema: it explains that designId pins aliases to that specific session registry, clarifying the interaction between the alias params and the session param, and frames cursor usage as an iterative loop rather than a one-shot field.

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

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

States a specific verb (Retrieve) and resource (one section of a compiled macro block blueprint), and enumerates the sections so an agent knows the granularity of the read. It does not explicitly name sibling tools like search_macro_blocks or list_blocks, so it is distinguishable but without direct sibling routing.

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 operational guidance for pagination ('Follow next cursors until complete') and notes the optional designId behavior, but never states when to choose this over search_macro_blocks or list_blocks, or when a single read is preferred over a search. Usage is implied rather than 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 already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that results are "complete layout scaffolds with explicit slot markers," which is useful output-shape context. It says nothing about how the many alias parameters (id/name/block/recipe/componentId) resolve or which wins, which is the main behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short clauses, front-loaded with the stage tag and the core verb+resource, with almost no waste. The bracketed stage label is slightly cryptic but earns its place by flagging pipeline position.

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 read-only retrieval tool with no output schema and 8 optional alias parameters, the description covers the basic contract but omits resolution precedence among aliases and how search matching works. Adequate but with clear 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%, so the schema documents every parameter including enums for density and environment. The description adds no meaning beyond that, so the baseline 3 is appropriate.

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

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

States a concrete verb and resource ("Search and retrieve complete layout scaffolds with explicit slot markers") and openly discloses that it is an alias of basecoat_page_architect, which prevents the agent from treating the two as separate capabilities. It does not, however, draw a clear line against sibling retrievers like get_macro_block or search_macro_blocks.

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 "[STAGE 1: ARCHITECT]" prefix implies this is the first step in a pipeline, which is weak but real usage context. There is no explicit when-to-use vs. when-not guidance and no mention of when to prefer this over basecoat_page_architect (its own base tool) or the block-level retrieval 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are content-addressed, cursor-paginated, and changed effective revisions invalidate prior cursors, which tells the agent cursors are not durable across revisions. It also notes that semantic IDs and implementation utilities are returned separately, which is meaningful for a read 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?

Three dense sentences, front-loaded with the core purpose before the override and pagination caveats. Every sentence carries substantive information. Some internal jargon (.basecoat/rhythm.json, content-addressed) costs a little readability but each phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, no-output-schema tool with annotations covering safety, the description supplies the missing return/behavior context (content-addressing, cursor invalidation, separate ID vs utility returns). What remains thin is guidance on routing between this and the other design-rules tools, which is the only real gap.

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

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

Schema description coverage is 100%, so all eight optional parameters are already documented in the schema, including aliases, the family example list, and the profile defaults. The description only echoes 'by family' and the pagination behavior without adding syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema carries the load.

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

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

States a specific verb and resource: reading the effective semantic rhythm profile by family, with explicit mention of project-local overrides. An agent can tell this is a read of rhythm/design-token data. However, it never differentiates itself from siblings like get_design_rules or basecoat_rules_enforcer, so the boundary between these tools is left to inference.

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 what is returned but gives no when-to-use guidance, no prerequisites, and no distinction from the rhythm-adjacent siblings (get_design_rules, enforce_rules). An agent must guess when this is the right tool versus the other rules-fetching 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety posture is covered. The description adds that it returns a structured quality report, but discloses nothing about what is checked, limits (e.g., 256KB max code), or how aliases behave, so it is only modestly additive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, front-loaded with the stage marker and alias note. No wasted text, though it is perhaps under-developed for a 10-parameter 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?

For a read-only inspection tool with a fully documented schema and clear annotations, this is adequate but thin: no output schema exists and the description only gestures at 'a structured quality report'. Usage routing and behavioral boundaries are not 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 description coverage is 100% and each parameter (code, html, markup aliases, environment, densityProfile, semanticProfile, enforceFsm) is documented in the schema. The description adds no parameter meaning, so the baseline of 3 for full coverage applies.

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

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

States a specific verb ('Audit') and resource ('HTML/Astro markup') plus the return type ('structured quality report'), and flags itself as an alias of basecoat_quality_inspector. It does not, however, distinguish itself from close siblings like validate_markup or validate_composition, leaving the boundaries somewhat implicit.

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 '[STAGE 4: QUALITY AUDIT]' prefix implies where this fits in a pipeline, which is useful workflow context. But it gives no explicit when-to-use vs validate_markup/validate_composition guidance, no prerequisites, and no 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety is covered. The description adds a small behavioral fact (the empty-args catalog-index behavior) but says nothing about pagination semantics, the cursor/response shape, or auth needs despite a read-heavy search surface.

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 short sentences, front-loaded with the alias note and ending on the empty-args special case. Every sentence carries information, though the alias framing consumes the prominent first position.

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 14-parameter, zero-required search tool with no output schema, the description omits the response/pagination behavior and the design/session parameters (designId, pageId, slotId, componentId). It covers the catalog-index case but leaves the richer session-scoped usage unexplained.

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 all 14 parameters are already documented in the schema, including enums and pagination. The description's mention of 'query, role, family, or tag' overlaps with the schema rather than extending it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search or list approved macro layout blocks') with filter dimensions. However, it opens by declaring itself an alias of search_macro_blocks, which muddies whether it is a distinct capability or a duplicate—an agent cannot tell from the description alone whether to prefer this tool or the sibling it mirrors.

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 documents the edge case 'When called with {}, returns the top-level macro block catalog index,' which is genuinely useful invocation guidance. It does not, however, say when to choose list_blocks over search_macro_blocks or get_macro_block, leaving the alias relationship ambiguous rather than routing the agent.

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=false, and destructiveHint=false, so the safety profile is fully covered. The description adds only scope detail ('50+', ApexCharts and SVG) and discloses nothing about pagination, result size limits, or filtering behavior beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact segments with no filler, and the identifying alias is front-loaded. The bracketed stage tag is slightly cryptic but does not waste much space.

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 read-only list tool with complete parameter documentation and rich annotations, the description is broadly adequate; no output schema exists so return values need not be explained. It stops short of noting result volume or filtering combinations, leaving minor gaps.

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

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

Schema description coverage is 100% and one enum is documented, so the schema already carries the parameter burden. The description adds no syntax, format, or aliasing detail (e.g., the query/search and id/componentId alias relationships) beyond what the schema spells out.

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

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

States a specific verb+resource ('List and filter ... ApexCharts and SVG data visualization blueprints') and identifies itself as an alias of sibling basecoat_list_charts, which helps the agent distinguish it from basecoat_get_chart_blueprint. The odd '[STAGE 3]' prefix is scaffolding rather than purpose, but the core statement is 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?

No explicit when/when-not guidance. 'Alias of basecoat_list_charts' implicitly routes the agent, but there is no indication of when to pick this over get_chart_blueprint, search_components, or basecoat_list_charts, nor any prerequisite or workflow condition.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral detail beyond that: results are capped at 8 and are 'compact summaries' rather than full definitions. It doesn't discuss query-matching behavior or empty-result handling, but for an annotated read tool this is solid.

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 front-loaded sentences: action+limit first, valid IDs second, next-step routing third. Every sentence carries information, though the ID enumeration is a bit list-heavy for the space it consumes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by disclosing the return shape (8 compact summaries) and the follow-up tools, which is what an agent needs to chain calls. Remaining gaps are minor: no guidance on empty results or on choosing among the alias parameters.

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 examples for query and intent, so the baseline is 3. The description adds a broader catalog of valid component IDs (dropdown-menu, tabs, badge, avatar, etc.) that extends beyond the schema's examples and directly helps construct valid queries, pushing it above baseline. The three overlapping identifier aliases (id/name/componentId) are left unexplained in both places.

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?

Clear verb+resource: 'Find ... compact component summaries by intent and/or query', with the result cap (up to 8) stated. It implicitly distinguishes 'component summaries' from macro-block search. It doesn't explicitly contrast itself with search_macro_blocks, so it stops short of full sibling differentiation.

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

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

The 'Next step: Call get_component_details or basecoat_component_syntax' line establishes this as the discovery entry point and routes the agent forward. However, it never states when to prefer this over search_macro_blocks or other sibling lookups, so usage is implied rather than explicit.

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, idempotent, non-destructive, closed-world behavior, and the description adds meaningful context beyond them: results are 'summaries and immutable refs only' and pagination is cursor-driven. That return-shape disclosure is genuine added value, though rate limits and cursor lifetime are unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler; the core purpose and the return/pagination caveat are both front-loaded and each clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter, zero-required search tool with no output schema, the description covers purpose, key filters, slot-scoping context, and return shape. It is nearly complete, missing only guidance on choosing among sibling search/list tools and cursor lifecycle.

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 every one of the 14 parameters is already documented in the schema. The description echoes the query/role/family/tag dimensions and the design/page/slot context, adding marginal framing but no syntax or precedence detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb ('Search') and resource ('approved macro layout blocks') plus the searchable dimensions (query, role, family, tag). An agent can tell it apart from the resource-oriented siblings, though it does not explicitly name search_components or list_blocks as the alternative for a different 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 implies usage by listing filter dimensions and noting that design/page/slot context narrows to slot-compatible roles, but it never states when to prefer this over search_components, list_blocks, or get_macro_block. No exclusions or alternatives are given.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the content of what is produced (v4 setup, OKLCH tokens, theme scripts), which is useful context, but says nothing about whether files are written, output format, or how defaults are applied. A 3 is appropriate with annotations carrying the safety burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence that front-loads the stage and the aliased tool before the output description. Nothing is wasted, though the bracketed stage label is somewhat meta rather than informational.

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 7 optional parameters fully documented in the schema and annotations covering safety, the description only needs to convey purpose and usage. It conveys purpose and output content but omits when-to-use guidance and any note on how the returned setup should be consumed, leaving a modest gap for a setup/config tool with no 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%, with clear enum explanations (framework, stylePack with aesthetic descriptions, environment) and default notes. The description adds no parameter guidance, so this sits at the baseline 3 where the schema does all 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 names a specific verb ("Generate") and concrete outputs (Tailwind CSS v4 setup, OKLCH tokens, theme scripts), and self-identifies as the "Alias of basecoat_setup_config," which resolves the duplication with that sibling. The "STAGE 1: ARCHITECT" prefix further situates it. It is clear what the tool does, though the alias framing leaves the relationship to basecoat_setup_config slightly ambiguous rather than fully distinguishing the two.

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

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

The "STAGE 1: ARCHITECT" label implies this is a first-step setup call, but there is no explicit statement of when to use this tool versus the canonical basecoat_setup_config, nor any prerequisites or exclusions. Usage is only inferred from the stage tag and alias note.

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 read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it enumerates what is checked and explicitly states it 'Does not render or evaluate dynamic code,' which is a meaningful scope limit an agent would not otherwise know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with a bracketed stage tag, then the action, then parameter hints, then constraints and the next step. Dense but each sentence carries information; no padding. Slightly list-heavy, which shaves a point.

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?

A read-only validation tool with 100% schema coverage and annotations covering the safety profile; the description supplies the check list, the dynamic-code exclusion, and the follow-up step. Only gap is that no output schema exists, and the description references a 'diagnostic output' whose shape is not characterized, but that is minor.

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

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

Schema description coverage is 100%, so the schema already documents code, html (as the alias), semanticProfile, and densityProfile with an enum. The description restates the code/html alias and optionality but adds no format or default detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource: statically check HTML/Astro source for a concrete list of Basecoat issues (migration errors, semantic rhythm, FSM bindings, nested cards, spacing). The scope is precise. However, it never distinguishes itself from the very similar siblings validate_markup, validate_design, and inspect_quality, so an agent cannot tell them apart from the description alone.

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

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

The '[STAGE 4: QUALITY AUDIT]' label and 'Next step: Fix any errors/warnings' sentence give useful workflow/workflow-position context (audit stage, then fix). But there is no explicit when-to-use vs alternatives guidance and no mention of the sibling validators, so selection between this and validate_markup/validate_design is left to inference.

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, and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: it returns 'totals plus paginated diagnostics' and warns that 'a plan-ready graph is not proof of rendered correctness', which tells the agent what validation does not guarantee.

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 short sentences, front-loaded with the action and scope, then the return shape, then an important caveat. No filler; the only blemish is the stray quotation marks around 'draft or complete mode'.

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 read-only validation tool with no output schema, the description covers the action, scoping, mode semantics, and the shape of the return (totals plus paginated diagnostics). It is a bit thin on how diagnostics are grouped, but nothing critical for invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents designId, pageId, cursor, revision, and the draft/complete enum. The description only echoes the mode and page scoping without adding format or interaction detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Validate a design session') plus scope options (a single page, draft/complete modes), so the agent knows exactly what is being validated. It does not, however, distinguish itself from the close siblings validate_composition and validate_markup, which an agent would need help telling apart.

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 mention of 'draft or complete mode' implies when each strictness level applies. But there is no explicit guidance on when to call validate_design versus validate_composition or validate_markup, nor any stated prerequisites (e.g. an existing session), so usage must be inferred.

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, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds meaningful scope beyond that: it is a static (non-executing) check and it names the specific failure classes it detects plus the diagnostic output containing errors/warnings. It stops short of describing result structure, but with no output schema this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the stage tag and alias relationship before the check scope, then closes with the next step. Dense but every clause carries information; the enumerated check list is long but relevant. No redundant 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 4-parameter, zero-required validation tool with no output schema, the description covers purpose, scope of checks, workflow stage, and the follow-up action, and hints at the diagnostic return. What an agent needs to call it correctly is essentially present; only explicit return-shape or required-parameter guidance is absent.

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 all four parameters (code, html alias, densityProfile, semanticProfile) are already documented in the schema, including the alias relationship and enum. The description adds no additional parameter-level syntax or format detail, which matches the baseline 3 when 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?

States a specific verb (statically check) and resource (HTML/Astro source), then enumerates exactly what it inspects: Basecoat migration errors, semantic rhythm, FSM bindings, missing scripts, nested cards, spacing and hierarchy. It also declares itself 'Alias of validate_composition' and tags '[STAGE 4: QUALITY AUDIT]', so an agent can place it against siblings without opening schemas.

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

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

Gives pipeline context via the '[STAGE 4: QUALITY AUDIT]' tag and a clear next step ('Fix any errors/warnings reported in the diagnostic output'). It also identifies itself as an alias of validate_composition, implying interchangeability. It does not, however, explicitly state when to prefer this alias over validate_composition or when validation is unnecessary.

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