Motion Menu

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the output structure (5–7 acts with purpose, patterns, density rating), the one-page protocol constraints (density wave pacing, one GL spectacle, 12–18 viewport-heights), and the fact that it returns metadata only.

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 dense, information-rich sentences with zero waste. The most important information is front-loaded, and each sentence adds distinct value: purpose, output structure, protocol constraints, next steps, and exclusions.

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

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

The description is complete for selection and invocation. It explains what the tool does, what it returns, what constraints it follows, and what to use next. Since there is no output schema, the description's specification of the act-map structure is essential and sufficient.

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 clear descriptions for both intent and acts, so the baseline is 3. The description adds no additional parameter-level meaning: it mentions the 5–7 act range but does not explain how to format 'intent' beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Design a complete page from intent.' It clearly distinguishes itself from siblings like compose_page and get_pattern by explaining it returns an act map, not pattern code.

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

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

It tells the agent when to use this tool (when designing a full page from intent) and what to do next: 'Feed the result straight to compose_page or get_pattern to retrieve the code.' The closing 'Returns metadata only — no pattern bodies' is an explicit exclusion clarifying that this tool is not for retrieving code.

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

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

With no annotations, the description carries the full burden. It discloses the return behavior (exactly which slugs were added/changed/removed, or current version and library counts) and instructs the caller to record the version. It implies a read-only operation (no mutation mentioned), which is reasonable for a 'check' tool. However, it doesn't state side effects or error handling explicitly, so it's not a perfect 5.

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

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

The description is front-loaded with a clear purpose and then explains usage and behavior. It's somewhat long (four sentences) but each sentence adds value—e.g., the reasoning about re-pulling only changed patterns is useful. There is no fluff, though it could be slightly condensed without losing 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?

Given there is no output schema, the description explains return values well: it lists the types of changes reported and mentions that 'library counts' are included with no arguments. It also tells the caller to record the version for future use, which is important for the tool's workflow. It doesn't describe exact response formatting or error cases, but for a simple read-only tool the completeness is adequate.

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

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

The schema covers the single parameter 'since' with a clear description, and the tool description adds extra context: where to source the version ('from `version` in a previous check_updates or /p/manifest.json') and the effect of omitting it. This goes beyond the schema's baseline, enriching the parameter's 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?

The description opens with a specific verb and resource: 'Check whether patterns you already built with have changed.' It clearly distinguishes itself from sibling tools like list_patterns and get_pattern by focusing on detecting changes (added, changed, removed) rather than listing or fetching. The purpose is unmistakable.

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 clear usage context: pass the version you built against to get a delta, or call with no arguments to read the current version and library counts. It implies a 'when to use' scenario (before re-pulling patterns) and contrasts with re-pulling all patterns, but it doesn't name alternative tools explicitly or state when not to use it. Strong 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?

With no annotations, the description discloses key behaviors: both modes require 'compose entitlement (Lifetime plan)' and `design_digest_version: 1`; it guarantees the plan 'can never contain a violation validate_combination would also reject — same rule engine, checked before each pick'; and it explains swap is 'literal text replacements (find→replace)'. It doesn't cover failure modes or error handling, but the core behavioral contract is well articulated.

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

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

The description is dense but every sentence adds new information: the two modes, the plan constraints, the HTML output contents, the entitlement/digest requirements, and the swap behavior. It's front-loaded with the primary purpose and avoids filler. Appropriate length for the tool's complexity.

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

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

Given a rich schema (100% coverage) and no output schema or annotations, the description covers the main decision paths: brief mode, sections mode, prerequisites, and swap. The only notable gaps are undefined behavior when neither `brief` nor `sections` is provided, and no mention of error handling; otherwise it's sufficient for an agent to choose and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant contextual semantics: it clarifies that `brief` and `sections` are mutually exclusive modes with different return types, enriches `sections` with the 'swap' mechanism (literal find→replace), and explains that `design_digest_version` is an acknowledgement of a read quality contract. It also documents constraints like 'one spectacle max, heavy never early, footer terminal' that affect how sections are accepted.

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 'Compose a complete standalone working page from Motion Menu patterns' and immediately contrasts with the plan mode via 'given a `brief` instead of `sections`'. This clearly distinguishes it from sibling tools like build_page (outputs HTML) and validate_combination (only validates) by framing compose_page as the orchestrator that produces either a full page or a validated plan. The verb 'Compose' + resource 'Motion Menu patterns' is specific.

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

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

The description explicitly states both invocation modes: 'Give explicit `sections` ... and a theme instead to get back one self-contained HTML document' and 'given a `brief` instead of `sections`, get back a structured COMPOSITION PLAN'. It names the prerequisite entitlement and design_digest_version. It hints at alternatives by referencing validate_combination and list_themes, though it never explicitly says 'don't use this for X'. Clear context, 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?

With no annotations, the description carries the full burden. It discloses that the tool retrieves a quality contract listing specific rules (anti-generic composition, motion lifecycle, etc.), implying a read-only getter. It does not explicitly state side-effect-free behavior or error conditions, but 'Get' and the content list provide sufficient transparency for a contract retrieval tool.

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

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

Two sentences, front-loaded with the core purpose, then usage timing, then value-add contents. Every sentence earns its place with no redundancy.

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

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

For a zero-parameter, no-output-schema getter, the description covers what it returns (machine-readable contract), when to use it (before build_page/compose_page), and what it contains (anti-generic rules, responsive requirements, etc.), making it self-sufficient.

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

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

The tool has zero parameters, so the description need not explain any. The baseline for 0 params is 4, and the description does not need to add parameter details because there are none.

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

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

The description clearly states a specific verb and resource: 'Get the machine-readable Motion Menu quality contract.' It also differentiates from siblings by instructing to call before build_page or compose_page, establishing its unique role as a prerequisite.

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

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

Explicit guidance is given: 'Call before build_page or compose_page.' This tells the agent exactly when to use this tool and implies its priority over sibling tools, leaving no ambiguity about invocation timing.

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

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

With no annotations, the description carries the full burden. It discloses what the tool returns (a bundle of design assets and instructions) and conditions usage ('before building a page'). While it doesn't detail the exact response format or state read-only behavior, the 'get' verb and content list make the behavior transparent enough for a parameter-free retrieval tool.

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

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

The description is a single sentence that front-loads the tool's purpose, lists contents, and ends with a clear call to action. Every phrase adds value, with no fluff or repetition.

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

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

Given there are no parameters, no output schema, and no annotations, the description fully covers what the tool does, what it contains, and when to use it. A minor omission is the explicit return structure, but for a simple 'get' of a known kit, the content list is sufficient.

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

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

The tool has zero parameters, so there is nothing to explain. Per the rubric, with 0 params the baseline is 4. The description adds no parameter-related details because none are needed.

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

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

The description clearly states the tool retrieves the Motion Menu build kit and enumerates its exact contents (design laws, act protocol, stack pins, gotchas, pattern index). It uses a specific verb ('get') and resource ('build kit'), and differentiates itself from sibling tools like get_pattern or list_patterns by representing the comprehensive aggregate starter kit.

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

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

The description explicitly instructs to 'Call this FIRST before building a page,' which is a clear timing directive. It does not name alternative tools or provide exclusion criteria, but the 'FIRST' instruction strongly implies it is the preferred entry point over siblings, earning a 4.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the key behavior of theme re-skinning: 'themed :root tokens prepended and every known JS/GLSL color literal rewritten,' which goes beyond the schema. It also clarifies the 'ready-to-use' wrapper behavior for framework, providing substantial transparency.

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

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

The description is composed of three sentences: the first states the core purpose, the second covers framework, and the third details theme behavior. It is well-structured and front-loaded with the primary function, though the theme explanation is somewhat verbose but still justified given its importance.

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

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

Given the absence of an output schema, the description adequately explains what the tool returns (HTML/CSS/JS, component wrappers) and covers parameter usage. It references list_themes for theme names, which provides contextual linkage to sibling tools. Overall, it is complete for a parameterized retrieval tool.

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

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

The schema has 100% parameter description coverage, so the baseline is 3. The description adds extra meaning beyond the schema by explaining the effect of the theme parameter (re-skinned bundle) and listing concrete framework extensions (react .tsx, vue .vue, svelte .svelte, vanilla .ts), enhancing comprehension.

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

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

The description clearly states the tool's function: 'Get one pattern by number, including its complete transplantable HTML, CSS and JS.' This uses a specific verb ('get'), a resource ('one pattern'), and specifies the return content, distinguishing it from sibling tools like list_patterns (listing) and get_theme (theme retrieval).

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

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

The description provides clear usage context for parameters: 'Pass framework to get a ready-to-use component wrapper' and 'Pass theme... to receive the bundle ALREADY re-skinned.' It references list_themes for theme names, giving an alternative tool reference, though it does not explicitly state when not to use this tool or compare it with alternatives.

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

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

With no annotations, the description carries the full burden. It discloses the nature of the response: token values, font stacks, a ready-to-paste :root CSS block, and a literal-to-color substitution map with exact string formats (hex, 0x, r,g,b triplets, GLSL vec3). This is specific behavioral detail about output content, though it does not mention error handling or read-only semantics.

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

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

The description is concise at two sentences and front-loads the core action. Every phrase adds value, including the technical parenthetical about exact string formats and the pointer to theme.html for building themes. No redundancy or fluff.

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 single parameter and no output schema, the description is largely complete, covering the main output components and their formats. It lacks explicit information about error behavior when a theme is not found, and could mention the relationship to list_themes, but overall it provides sufficient context for the agent.

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

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

The schema already provides full description of the 'name' parameter (100% coverage), including an example. The description does not add additional meaning beyond what the schema offers, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Get one theme' and enumerates the specific contents returned (token values, font stacks, CSS block, substitution map), which distinguishes it from sibling tools like list_themes or get_kit. The resource and scope are 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?

No explicit when-to-use versus alternatives is provided. The phrase 'Get one theme' implies fetching a single theme by name, and the mention of /theme.html suggests a human workflow, but it does not state, for example, to use list_themes to discover available themes or to use get_kit for other design resources.

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

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

With no annotations, the description carries the burden of disclosing behavior. It specifies the exact output format ('number slug <role> [tags] · title'), explains the meaning of ROLE and SLUG, and states the behavior when called with no arguments. It does not cover pagination or sorting, but for a list tool this is sufficient transparent detail.

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

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

The description is a single dense paragraph that front-loads the core purpose, then efficiently covers output format, role semantics, slug importance, filtering options, and no-arg behavior. Every sentence earns its place and there is no fluff or repetition.

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 list/filter tool with 5 optional parameters and no output schema, the description is complete. It explains the output format, the meaning of roles, the various filter dimensions, and the no-argument case. No critical information is missing for an agent to confidently use the 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% with inline descriptions, so baseline is 3. The description adds value by grouping the filter dimensions ('by tag, by collection slug, by free-text query, or by legacy section letter') and providing concrete examples like 'seams-handoffs'. It also adds conceptual guidance on when to filter by role versus tag, which helps parameter selection beyond the schema.

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

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

The description starts with a clear verb and resource: 'List Motion Menu patterns.' It distinguishes itself from siblings like get_pattern by describing the output as a list of rows with roles and tags, and it emphasizes the slug as the permanent identity, implying this is the browsing/searching tool rather than a single-pattern fetcher.

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

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

The description gives explicit context on when to use certain filters: 'filter by it when you are building a page rather than hunting an effect' and 'Call with no arguments to see the whole catalogue and its tag vocabulary.' It does not explicitly name alternative tools like get_pattern for single-pattern lookups, so it falls short of a 5, but the usage context is clear.

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

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

No annotations exist, so the description must convey behavior on its own. It states the tool lists themes with specific fields, implying a read-only operation, but it does not disclose possible variations like filtering, pagination, or any side effects. Adequate for a simple list tool, but lacks deeper behavioral detail.

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

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

The description is a single sentence, front-loaded with the main action. It efficiently includes the key output fields and usage context without any unnecessary words.

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

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

For a zero-parameter list tool with no output schema, the description sufficiently covers what it does and what it returns (name, mode, label). It aligns well with sibling tools and leaves no critical gaps for the intended use.

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

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

The tool has zero parameters and an empty input schema, so there is nothing to explain beyond schema. The description adds no parameter information, but the baseline of 4 is appropriate given the 100% schema coverage and absence of 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 uses a specific verb 'List' and identifies the resource 'Motion Menu themes' with its return fields (name, mode, label). It also references get_pattern/get_theme, differentiating itself from sibling tools like list_patterns.

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 phrase 'for get_pattern/get_theme' provides clear context on when to use this tool, indicating it supplies theme data for those operations. It does not explicitly state alternatives or when not to use it, but the context is unambiguous.

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

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

With no annotations provided, the description carries the full burden. It discloses the key behavioral trait: 'Returns metadata only (number, slug, title, role, score, reason, compatible_with),' clarifying that it does not return code and that follow-up via get_pattern is required. It also mentions compatibility suggestions and exclusion behavior implicitly through 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 focused sentences, front-loaded with the tool's purpose, then immediately clarifying the output format and next step. No wasted words; every sentence earns its place.

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

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

The description is complete for a recommendation tool: states what it does, how to invoke it, what it returns, and how to follow up for actual code. The input schema covers parameters well, and the description sufficiently explains return values given there is 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 coverage is 100%, so baseline is 3. The description adds value by elaborating the 'intent' parameter with examples ('industry, style, mood, technical needs') and clarifies that results include 'compatibility suggestions,' enriching what the schema alone provides.

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

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

The description clearly states the tool provides 'intent-aware pattern recommendations' based on a building intent, and returns scored results with reasons and compatibility suggestions. It explicitly distinguishes itself from get_pattern by saying 'Call get_pattern to retrieve the actual code for any recommendation,' positioning it as a recommendation-only tool.

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

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

The description gives clear context: use it when you need scored pattern recommendations based on a descriptive intent. It also points to get_pattern for code retrieval, providing a relationship to a sibling tool. It doesn't mention exclusions or when not to use it, but the context is strong.

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

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

No annotations are provided, so the description carries the burden. It discloses the full report structure: overall score, per-pair analysis, style/industry coherence, intensity balance, page-flow coverage, and warnings. This provides clear expectations, though it stops short of stating read-only behavior explicitly.

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 zero filler. Each clause adds value: purpose, input, output, and usage timing. The enumeration of report sections is dense but directly informs the agent.

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

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

For a tool with one parameter, no output schema, and no annotations, the description covers input, output, and when to invoke it. It gives enough context for an agent to select and use it correctly in the compose_page workflow.

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 the only parameter 'components' described as 'Pattern slugs or numbers to validate together' in both schema and description. The description adds contextual intent ('you plan to combine on a page') but no additional format or constraint details, so 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 'Check whether a set of patterns work well together' — a specific verb and resource. It also distinguishes itself from siblings by detailing the compatibility report and explicitly instructing to call before compose_page.

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

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

It gives a clear directive: 'Call BEFORE compose_page to catch mismatches early.' This provides explicit timing context. However, it doesn't mention when not to use it or alternative tools like recommend_patterns, so it's strong but not exhaustive.

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