basecoat-ui

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds real value beyond them: replay with the same operationId returns the original receipt, committed mutations always acknowledge success, and oversized optional fields may be omitted with truncated:true.

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, front-loaded with the core action and the atomicity contract. Every sentence carries information; no filler or restatement of the tool name.

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 high-complexity mutation tool with no output schema and 0% parameter documentation, the description covers idempotency, truncation, and the source-file boundary well. It omits revision-conflict behavior, permission requirements, and the contents of the receipt, leaving gaps an agent author would need to close.

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

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

Schema description coverage is 0%, so the description must compensate. It names expectedRevision and operationId and explains operationId's replay semantics, but says nothing about designId or the structure of the operations array, whose meaning rests entirely on the schema's const values and required-field shapes.

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

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

The description gives a specific verb and resource: 'Apply one atomic list of design graph operations,' scoped with expectedRevision and operationId. It clearly distinguishes this as a mutation-style patch tool, though it never names or contrasts any sibling such as validate_design or begin_design.

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

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

Atomicity and the same-operationId replay rule imply when the tool is appropriate, and 'Does not write application source files' is a useful boundary. However, there is no explicit when-to-use/when-not guidance or reference to alternatives among the ten sibling 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 non-readOnly, idempotent, non-destructive, closed-world. The description adds genuinely new behavior: persistence location under the host project root, registry pinning and hash verification, and the truncated:true receipt fallback after commit. It stops short of error/conflict semantics when the same designId is reused with different decisions.

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

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

Front-loaded with the core action, then parameters, then behavior, in four tight sentences with no filler. Slightly dense and packs several distinct behaviors into the trailing sentences.

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

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

Covers the essentials for a mutation with no output schema: persistence, idempotency, registry pinning, and receipt truncation. Missing is what a session enables downstream and any failure/conflict behavior, which matters for a stateful creation tool sitting among several design siblings.

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

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

Schema description coverage is 0%, so the description must carry the load. It names designId, profile, operationId and optional decisions, and clarifies profile may be an alias or ref; it also flags decisions as optional. It adds nothing about the nested decisions object's accepted keys/values or the meaning of operationId beyond the schema's string constraints.

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+scope: 'Create a persistent design session under the host project root.' An agent can distinguish it from read-only siblings like get_design_context and apply_design_patch. However, it never names a sibling or explicitly contrasts itself with the other design-lifecycle tools.

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

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

Usage is only implied: creating a session is naturally the precursor to patching/validating a design, and the idempotency note hints at safe retries. There is no explicit when-to-use, when-not-to-use, or naming of an alternative tool.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds a concrete behavioral constraint by stating the response is bounded to 2000 UTF-8 bytes, and discloses that the result contains a minimal template, dependencies, and composition tips. This adds value beyond the annotations, though the size-bound phrasing is slightly ambiguous.

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

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

The description is two short, front-loaded sentences with no filler. The core retrieval statement comes first, and the response-size note is a useful addition. Every sentence earns its place.

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

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

For a simple read-only lookup with two required parameters and no output schema, the description covers the main invocation facts: input language, single-component resource, and response contents and size limit. It does not mention response format or how to discover valid IDs, but the sibling search_components tool likely fills that gap. Overall it is sufficiently complete for a correct call, with minor discoverability 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 0%, so the description must compensate for missing parameter documentation. It maps the environment parameter to Astro or HTML and implies id selects a single component, but it never explicitly defines id as a component identifier or explains how valid ids are discovered. This is only partial compensation for the absent schema descriptions.

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

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

The description uses a specific verb, 'Get', and names a concrete resource: one minimal component template with dependencies and composition tips, scoped to Astro or HTML. This clearly differentiates it from search_components (searching) and validate_composition (validating), and 'one minimal' signals single-item retrieval rather than a list operation.

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 guidance is given about when to use this tool versus search_components or validate_composition. The description does not say to use search_components first to find an id, nor does it mention when validation would be more appropriate. Usage context is left entirely 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 cover the safe-read profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real behavior: revision must be pinned on the first read and matched on continuations, and it explicitly disclaims side effects ('Does not create sessions'). It does not describe pagination/cursor behavior, which is the main remaining 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?

Three dense sentences with no filler, and the view enumeration is front-loaded so an agent can key on it immediately. The revision rule follows logically, though the parameter list inside the sentence reads a bit run-on.

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 six-parameter, read-only, no-output-schema tool this is only partly adequate: the view selection and revision protocol are covered, but the roles of cursor, nodeId, and pageId are never explained in either the schema or the description.

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

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

Schema description coverage is 0% across six parameters, so the description carries the full burden. It only explains the 'view' enum and the designId exclusion for 'sessions'; cursor, nodeId, pageId, designId, and revision semantics are left entirely undocumented, leaving most parameters opaque.

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') and resource ('focused design view') and enumerates the seven selectable views, so the agent knows exactly what it retrieves. It also explicitly disclaims session creation, which cleanly separates it from begin_design, though it doesn't position itself against the other read-style siblings.

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

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

Gives one concrete conditional rule ('sessions' takes no designId) and a revision-matching rule for continuations, which implies how to chain calls. However, there is no guidance on when to pick a given view over a sibling tool like get_component_details or get_rhythm_rules.

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 real semantic context beyond that: recipes are structural metadata, not executable runtime code. It omits pagination behavior (limit/cursor) and any authorization or scope notes, so it is useful but not rich.

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, and the core capability is front-loaded before the clarifying caveat. 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 4 undocumented parameters, no output schema, and no annotation gaps to lean on for return shape, the description leaves an agent guessing about how to identify a recipe and how to page results. The metadata-vs-runtime clarification is valuable but does not fill the operational 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 0% for 4 parameters, so the description must compensate and largely does not. Its enumeration of states/events/guards/actions/transitions effectively documents the 'section' enum, but 'recipe', 'limit', and 'cursor' (including the 32-item page cap and cursor-based paging) are left entirely unexplained.

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') and enumerates the exact resource kinds (states, events, guards, actions, transitions) it returns, so an agent knows what it gets. It does not differentiate itself from siblings like validate_design or get_design_context, but no sibling appears to overlap this FSM-metadata niche.

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 prerequisites, and no named alternative. The closing clause clarifies what a recipe is but says nothing about when this tool should be selected over validate_composition or other design 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/non-destructive, so safety is covered. The description adds genuinely new behavior: retrieval is sectioned and paginated, requiring the caller to iterate next cursors until complete, and that designId scopes alias resolution to a session registry.

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 resource and section list, then pagination, then the optional scoping parameter. Dense and largely waste-free, though the parenthetical section list duplicates the schema enum.

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

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

With no output schema and 0% parameter description coverage, the description carries the full burden. It covers pagination and section enumeration, but leaves id vs idOrRef, default section behavior, and error semantics undocumented for a 5-parameter tool.

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

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

Schema coverage is 0% across 5 parameters. The description partly compensates by listing the valid section values and explaining designId's registry-pinning effect, but it never explains the difference between the two look-alike identity parameters id and idOrRef, which is the most consequential ambiguity for correct invocation.

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 section types, which lets an agent distinguish it from the search-oriented sibling search_macro_blocks. It stops short of naming a specific alternative the way a 5 would.

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?

"Follow next cursors until complete" is actionable pagination guidance and the designId sentence hints at when to supply it. However, there is no explicit when-to-use vs when-not, and no routing to a sibling such as get_component_details for non-macro blocks, so usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety bar is low, yet the description adds real behavioral context: results are content-addressed and cursor-paginated, and changed effective revisions invalidate prior cursors. That cursor-invalidation rule is genuinely useful and not derivable from 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?

Three sentences, front-loaded with what is read, followed by the separate-return caveat and pagination semantics. Dense but each sentence carries information; no filler.

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

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

No output schema exists, and the description only partially compensates by sketching return structure (IDs/utilities separate, content-addressed). With 0% param coverage and no output schema, gaps remain around limit and profile semantics, leaving the definition adequate but incomplete.

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

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

Schema description coverage is 0%, so the schema documents nothing. The description indirectly explains 'family' (read by family) and 'cursor' (cursor-paginated, invalidated on revision change), but leaves 'limit' and 'profile' entirely unaddressed, so it only partially compensates for the coverage gap.

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

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

States a specific verb (read) and resource (effective semantic rhythm profile) with scope qualifier 'by family'. It is clearly distinct from the design/component/macro siblings, but the tool name says 'rhythm rules' while the description says 'rhythm profile', a minor terminology drift.

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: you read the rhythm profile here, and semantic IDs/utilities are 'returned separately' (hinting at other tools). There is no explicit when-to-use/when-not, no named alternative, and no prerequisite stated.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds genuinely new behavioral facts beyond them: the hard cap of 8 results, empty-list-on-no-match, and that no markup is returned. It does not mention ranking or ordering of results, but the additions are real value.

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

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

A single compact sentence with the result cap and the empty-result behavior front-loaded, and no filler. It is perhaps overly terse given the undocumented param distinction, but nothing in it wastes 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 two-param search tool with rich annotations and no output schema, the description covers the essentials (cap, empty result, no markup). It stops short of defining the intent/query distinction or result ordering, which are the remaining gaps an agent would hit in practice.

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

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

Schema description coverage is 0%, so the description carries the burden for both params. It clarifies that both are optional and combinable ('and/or'), but never explains what 'intent' means versus 'query' — the central semantic distinction an agent needs to fill them correctly. Partial compensation only.

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 (Find) and resource (component summaries), and scopes it with 'up to 8 compact' and 'by intent and/or query'. 'Compact summaries' implicitly distinguishes it from get_component_details, though it never names the sibling or explains the boundary 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?

The parenthetical '(either field may be omitted)' tells the agent both params are optional, which is useful invocation guidance. However, there is no explicit when-to-use-this-vs-validate_composition/get_component_details routing, so usage must be inferred from 'compact summaries'.

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, so the safety profile is covered. The description adds real value beyond that: results are limited to 'approved' blocks, it returns 'summaries and immutable refs only', and it discloses cursor-based pagination for larger result sets.

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; the primary purpose is front-loaded and the return/pagination caveat follows immediately.

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

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

With no output schema and 10 undocumented parameters, the description successfully conveys the result shape (summaries + refs) and pagination, but omits the meaning of limit and parentNodeId and never clarifies the approved-only constraint's implications. 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 0% across 10 parameters, so the description must compensate. It maps the main filters (q/role/family/tag) and alludes to designId/pageId/slotId via 'design/page/slot context', but leaves limit, cursor semantics, and parentNodeId entirely unexplained.

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 approved macro layout blocks') and enumerates the filter dimensions (query, role, family, tag). It distinguishes the tool from a generic search, though it never names the nearest sibling search_components to clarify the boundary.

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

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

Implies usage via 'Optional design/page/slot context filters to slot-compatible roles', which tells the agent when the context filters are relevant, and 'use cursors for more' covers continuation. However there is no explicit when-not-to-use guidance or routing to an alternative tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the agent knows this is a safe, deterministic read. The description adds the static-only constraint and enumerates check categories, but doesn't mention what a successful/failed check returns (no output schema) or any limits on code size beyond what the schema maxLength provides.

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?

One dense sentence enumerating checks and one sentence covering inputs plus the non-rendering caveat. Front-loaded with the core action; no filler. Slightly list-heavy but 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?

Given a 4-param tool with 0% schema coverage and no output schema, the description tells what it checks and the input names, and clarifies no dynamic evaluation. It still leaves the parameter semantics (profiles, code vs html) and the nature of the result incomplete, so it's minimally adequate but has gaps for correct invocation.

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

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

Schema coverage is 0%, so the description must compensate. It mentions passing 'code' or alias 'html' and optionally semanticProfile and densityProfile, but gives no meaning for the enum values (comfortable/compact), no format for semanticProfile (max 64 chars), and no explanation of when to use code vs html. The alias relationship is noted but semantics beyond names are absent.

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 (statically check) and resource (HTML/Astro source) with clear scope: Basecoat migration errors, semantic rhythm, FSM bindings, missing scripts, nested cards, spacing/hierarchy. Distinguishes from sibling validate_design (which covers design validation) by focusing on static composition/lint checks.

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?

States it's a static check and explicitly says 'Does not render or evaluate dynamic code,' which is a useful boundary. However, it doesn't explain when to use this versus validate_design or apply_design_patch, nor any prerequisites or typical workflow positions.

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), but the description adds genuinely useful context: it discloses the return shape (totals plus paginated diagnostics) and warns that a plan-ready graph is not proof of rendered correctness, framing the tool's 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 tightly packed sentences, front-loaded with the action and scope and followed by the one caveat that matters. No filler.

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

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

With no output schema, the description usefully does describe the return (totals plus paginated diagnostics) and the pagination model. The remaining gap is parameter semantics for cursor/revision/designId, though annotations already carry the safety profile.

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?

Five parameters with 0% schema description coverage, yet the description only obliquely touches two of them ('draft or complete mode' maps to mode, 'or one page' hints at pageId). cursor, revision, and designId semantics remain entirely undocumented, so the description does not compensate for the coverage gap.

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

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

States a specific verb (validate) and resource (design session or one page) with a scope qualifier (draft or complete mode). Clear without opening the schema, but it never distinguishes itself from the sibling validate_composition, so an agent must guess which validator applies.

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?

Implies usage by naming the two modes and the optional page-level scope, but gives no explicit when-to-use rule, no prerequisites, and no guidance on choosing this tool over validate_composition or when draft vs complete is appropriate.

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