Motion Menu

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

Despite no annotations, the description fully carries transparency: 'Deterministic, no LLM' and 'every finding cites the exact matched HTML' assure reliability. It also details the output format (score 0-100, per-section tells, prescriptions) and hints at the underlying graph shared with recommend_patterns, adding behavioral context beyond any structured metadata.

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?

At about 70 words, the description is tightly packed with no filler. Each clause introduces a new fact: the audit criteria, determinism, output components, and follow-up tool calls. It is front-loaded with the core action and then provides necessary detail.

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 thoroughly explains return values (ai_shaped_score, per-section evidence, page-level tells, prescriptions) and even names the next tool calls to fetch/validate them. It also conveys the tool's read-only nature indirectly via 'Audit', though it never explicitly states that at least one of url/html must be provided; however, the schema's 'alternative to html' phrasing covers that implication.

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?

Both url and html have rich schema descriptions covering fetch constraints, size caps, timeouts, and one-page-per-call, so schema coverage is 100%. The tool description adds no parameter-specific meaning beyond what the schema already provides, 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?

The description opens with 'Audit an EXISTING page' — a specific verb and resource — and enumerates the exact patterns checked ('numbered steps, a centered hero...'), clearly distinguishing this from sibling creation tools like build_page/compose_page. The mention of 'any AI builder, any stack' broadens the resource scope without losing specificity.

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 establishes clear usage context: existing pages from any AI builder, plus 'FREE, no key required' signaling no authentication barrier. It implies use before redesign or replacement of sections, but does not explicitly name when not to use it or compare it to similar sibling tools like get_design_digest.

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

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

No annotations are provided, so the description must bear the full burden of behavioral disclosure. It clearly states the output is metadata only (not pattern bodies), follows 'the one-page protocol' with specific constraints (density wave pacing, one GL spectacle, 12–18 viewport-heights), and that it returns an act map. This gives the agent an idea of what to expect. However, it doesn't clarify if the tool makes any external calls, whether it has side effects, or whether any inputs are destructive—but as a design tool, this is likely non-destructive. The description adds decent context but lacks depth on edge cases.

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

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

The description is three sentences, each dense with meaning. It front-loads the core purpose, follows with output structure and design constraints, and ends with a clear call-to-action (feed to get_pattern). Every sentence earns its keep with zero 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?

Given the tool has 6 parametersholistic, an output schema absent, and no annotations, the description covers the core output format, the design protocol constraints, and the recommended downstream step. It doesn't explain how to interpret the density rating or act purposes in detail, but that may be understood from the get_pattern context. The description is comprehensive enough for an agent to understand the tool's role in the design pipeline, though some implementation details (like error handling) are not 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%, so the schema already documents all parameters: intent, acts, seed, history, exclusions, and direction_id. The description adds value by explaining the output format (act map) and its relationship to get_patternable, but it doesn't enrich parameter semantics beyond the schema. For example, it doesn't explain the interplay between acts and direction_id beyond what the schema offers. 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 starts with a specific verb 'Design' and defines the resource as 'a complete page from intent.' It clearly states what the tool does: produce a page design plan with acts, patterns, and density ratings. It also differentiates it from siblings by stating it 'Returns metadata only' and explicitly says to feed output to get_pattern for 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?

The description gives strong context: use this tool to design a page, and then 'Feed the result straight to get_pattern to retrieve the code.' It names a sibling (get_pattern) and describes the workflow. However, it doesn't explicitly exclude other tools or mention when not to use this one. The purpose is clear enough that an agent could infer usage, but exclusions are not 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?

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 must convey behavioral traits. It goes beyond a generic 'get' by listing the contract's contents (anti-generic composition rules, motion lifecycle, etc.), disclosing what the agent will receive. It does not mention side effects, but for a retrieval tool this is sufficient. The description adds substantial context beyond the tool name.

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 purposeful. The first states the resource and purpose; the second gives usage timing and content details. Information is front-loaded and there is no wasted verbiage.

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 tool with no output schema, the description is fully complete. It states what the contract is, when to call it, and what it contains. An agent needs no additional information to correctly invoke and understand the tool's role.

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 schema coverage is trivially 100%. Per the instruction baseline for zero-parameter tools, a score of 4 is appropriate. The description doesn't need to explain parameters, and it doesn't pretend to.

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 ('Get') and a precise resource ('the machine-readable Motion Menu quality contract'). It clearly conveys what the tool does and implicitly differentiates it from sibling tools by highlighting its role as a contract retrieval, not a build or audit 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?

Explicitly instructs to 'Call before build_page', giving direct usage context. It also lists what the contract defines, which informs when an agent would need it. While it doesn't mention alternatives, the placement before build_page is a clear trigger.

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?

No annotations are provided, so the description carries the full burden. It discloses the return content (HTML/CSS/JS and optional wrappers) and the effect of the 'framework' parameter. It does not mention side effects, but for a read operation this is sufficient.

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 pack the core purpose, output details, and parameter behavior with zero waste. The key action is front-loaded, making it easy to parse.

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 mostly complete for a single-record fetch. However, it does not explicitly state that either 'slug' or 'number' is required (since required params are 0), which could leave the agent uncertain about argument requirements.

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 meaning by explaining that 'slug' is preferred and that passing 'framework' yields a ready-to-use wrapper, which clarifies the purpose of the framework parameter beyond its enum values.

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

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

The description clearly states the verb 'Get' and the resource 'one pattern by number', and specifies the output includes 'complete transplantable HTML, CSS and JS'. This distinguishes it from siblings like 'list_patterns' which presumably return multiple items.

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 on when to use the tool (to retrieve a single pattern) and how to use the 'framework' parameter to get a wrapper. It does not explicitly mention alternative tools or exclusions, but the singular 'one pattern' implies differentiation from list 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?

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 are provided, so the description carries the full burden of behavioral disclosure. It explains the output (three directions with specific attributes), the return of direction_id, and the dependency on the same brief and seed for build_page, which is a useful behavioral constraint. However, it does not disclose potential side effects, failure modes, or performance characteristics, which is a moderate gap for a creative generation 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 with zero wasted words. The main purpose is front-loaded, followed by the specific output components and the crucial linkage to build_page. Every sentence contributes value, making it both concise and logically structured.

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

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

For a tool that lacks an output schema, the description adequately explains what is returned (three design directions, each defining layout grammar, typography, imagery, motion physics, density rhythm, avoid rules) and how the direction_id is used downstream. It covers the essential usage context but does not elaborate on selection criteria among the three directions or any constraints on the brief's format, which are minor omissions given the tool's creative nature and sibling tool complement.

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 both parameters (brief and seed) are already documented in the schema. The description adds minimal extra meaning: it clarifies that the brief is a 'business/page brief' and implies seed is for reproducibility, but these are near-duplicates of the schema descriptions. The baseline of 3 applies since the schema does the heavy lifting and the description offers only marginal amplification.

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 ('Turn') and names the resource ('business/page brief') and the output ('three deliberately different design genomes'). It explicitly differentiates from build_page by stating that the returned direction_id is passed into build_page, clarifying its role as a precursor step. This allows an agent to distinguish propose_directions from its siblings without ambiguity.

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 clearly indicates when to use the tool: when you have a brief and want three distinct design directions before choosing components. It also provides the follow-up step (passing direction_id into build_page with the same brief and seed), which guides sequential usage. However, it does not explicitly state when NOT to use it or name alternative tools for other scenarios, leaving some inference to 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?

With no annotations, the description carries the full burden. It discloses that the tool returns metadata only, includes compatibility suggestions, and is intent-aware, implying a read-only operation. It does not explicitly state side effects or rate limits, but for a recommendation tool this is sufficient.

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 no filler. The first sentence states purpose and input, the second explains output and the follow-up tool. Information is front-loaded and every word 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 explains the output fields (number, slug, title, role, score, reason, compatible_with) and the relationship to get_pattern, which is critical for an agent to know. It does not elaborate on parameter behaviors like seed reproducibility or context exclusions, but the schema covers those. For a tool with no output schema, this is adequately complete.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal semantic value beyond what the schema provides, only hinting at intent and compatibility. The baseline of 3 is appropriate because the description does not materially enhance parameter understanding.

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

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

The description clearly states a specific verb ('recommend'), a resource ('patterns'), and the trigger condition ('Describe what you are building...'). It explicitly distinguishes from siblings by noting it returns metadata only and directs to get_pattern for code, so an agent can tell it apart without inspecting 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?

The description implies when to use it (when you need scored pattern recommendations) and explicitly names get_pattern as the next step for retrieving code. However, it does not explicitly state exclusions or compare to other siblings like list_patterns or propose_directions, 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?

With no annotations provided, the description carries the full burden and largely meets it: it discloses that the tool returns a report (not a mutation) and details the report's contents including warnings for duplicate roles, missing positions, and heavy patterns. It implies a non-destructive analysis. It does not explicitly state 'makes no changes' or cover auth/limits, but for a validation tool the return-behavior disclosure is strong.

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 purpose and the usage call-to-action. The detailed list of report components is justified because there is no output schema, so it is the only documentation of return contents. Efficient with no filler, though slightly long due to that necessary enumeration.

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

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

Complete for a single-parameter validation tool: input format is covered by schema plus description, output content is fully enumerated (essential given no output schema), and usage timing is stated. Minor omissions—explicit non-destructive statement and any performance limits—are non-critical for a pre-build analysis call.

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 already documents 'Pattern slugs or numbers to validate together,' so the description's mention of 'slugs (or numbers)' adds nothing beyond the structured field. Baseline 3 is appropriate since the schema carries the burden and the description contributes only contextual framing, not new parameter detail.

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 pair ('Check whether a set of patterns work well together') and enumerates the concrete outputs (overall score, per-pair analysis, style/industry coherence, intensity balance, page-flow coverage, warnings). It is clearly distinguishable from siblings: it evaluates pattern combinations pre-build (vs audit_page for existing pages, recommend_patterns for suggestions, verify_repair for fixes).

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 timing guidance: 'Call BEFORE building to catch mismatches early,' which positions it relative to build_page as a pre-build gate. It does not name explicit sibling alternatives or state when NOT to use it, but the before-building directive is clear contextual direction that an agent can act on.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states the return value (score, delta, tells with fix instructions) and adds useful context about being free and requiring no key. It does not go into error handling or rate limits, but it covers the essential behavior well.

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 sentence that packs many clauses and a colon-separated list. It is economical with words, but the structure is slightly overloaded; breaking it into two sentences would improve readability. Still, every 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?

Given the absence of an output schema, the description adequately explains the return values (fresh score, delta, residual tells with fix instructions). It also covers prerequisites (rewriting from audit_page), usage pattern, and cost, making it complete for an AI agent to decide when and how to invoke it.

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

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

The schema already describes parameters well (100% coverage), but the description adds crucial relationship semantics: it explains that baseline and baseline_score are alternative ways to pass the prior audit, and that baseline_score is derived from baseline when omitted. This goes beyond the schema's simple 'optional' labels.

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

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

The description uses a specific verb ('re-audit') and resource ('a page you just rewrote'), clearly distinguishing it from the sibling audit_page tool. It also states the context (from audit_page's prescriptions) and the outcome (pass/fail verdict), making the purpose 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?

The description implies when to use the tool: after rewriting a page based on audit_page's prescriptions. It gives clear contextual guidance but does not explicitly name alternative tools or list when-not-to-use conditions, so it falls short of a perfect 5.

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