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

Annotations already declare readOnlyHint and idempotentHint, and the description goes well beyond them by revealing specific behaviors: it reports file:line for missing assets, deliberately catches macOS-vs-Linux case-sensitivity failures, and treats CSS custom properties as references. This is exactly the kind of non-obvious behavioral context that helps an agent predict side effects and limitations.

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 the core behavior in the first sentence, then adds two high-value edge cases. Every sentence earns its place: none restate the tool name or repeat schema details, and the length is appropriate for the 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 the output schema, full parameter documentation, and read-only annotations, the description closes the important gaps: asset scope, reporting format, the platform-specific failure mode, and the theme-contract nuance. An agent has everything needed to decide to invoke it and what to expect.

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 real meaning to the check_theme parameter by explaining that var(--token) is a reference and that a custom property defined only inside a dark-mode media query has no value in the default state. It also clarifies the internal-link scope covered by check_links.

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: 'Follows every image, stylesheet, script, icon and internal link... and confirms the file is really there.' It also states the concrete output ('Reports file:line'), which clearly differentiates it from the sibling check tools like check_copy or check_responsive.

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 a clear context for when this tool matters, especially the case-sensitivity trap that cannot be caught on the building Mac. It does not explicitly name sibling alternatives or say 'use this instead of X', but the scope is specific enough that an agent can recognize it as the asset-existence check among the 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?

Even though annotations already declare read-only and idempotent behavior, the description adds useful behavioral context: the specific issue categories it checks and the output contract of 'what, why, who says so, and the better move.' No contradiction with the annotations exists.

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 compact and front-loaded, with the core action first, then the rule list, then the parameter/output contract. It is slightly redundant because 'Run ... over a folder, or over a block of text' is restated in 'Pass either directory or text,' which prevents a top score.

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 an output schema and sufficient annotations present, the description covers the important operational aspects: input modes, the rule set, and the result format. The main gap is the implicit relationship to sibling tools like check_honesty and review_site, which affects complete context.

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

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

The schema already documents all three parameters with full coverage, so the baseline is a 3. The description adds meaning beyond the schema by stating 'Pass either directory or text,' which conveys that these are alternative input modes rather than interchangeable or combinable fields.

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

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

The opening line states a specific action and resource: 'Run the copy and honesty rules over a folder, or over a block of text pasted straight in.' It also lists concrete examples of what the rules catch. However, it does not differentiate check_copy from the sibling check_honesty, which overlaps with the 'honesty rules' wording.

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 by describing the folder/pasted-text modes and the rule categories, but it never names alternatives or says when not to use it. Given the sibling list includes check_honesty)Skip, an explicit contrast would have made the guidance stronger.

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

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

Beyond the readOnly and idempotent annotations, the description adds meaningful behavior: it reports file:line, defines the 'fail' status as error-only, explains warnings as items to verify, and describes how entries in .honesty.json silence findings. This gives the agent a clear model of tool behavior without contradicting the annotations.

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

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

The description is organized into three purposeful paragraphs: what is scanned, the attribution nuance, and the reporting/status behavior. Every sentence adds relevant information, and the most important scoping details are front-loaded.

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

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

Together with the fully described schema, annotations, and output schema, the description covers the scan scope, the subtle attribution heuristic, the ledger workflow, and the output status semantics. Nothing essential for invoking the tool correctly is missing, apart from sibling routing, which is captured separately.

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 input schema covers all five parameters with descriptions, so the schema already carries the parameter meaning. The description references the ledger and directory behavior but does not need to add per-parameter detail. The baseline of 3 applies because the description does not materially enrich parameter semantics.

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

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

The description names a specific verb and resource: it scans a site for content claiming something nobody earned, with concrete examples like testimonials, star ratings, 'as seen in', and attributed quotations. This is clear and not tautological, but it does not explicitly distinguish itself from sibling tools such as check_copy or check_single_source.

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 no explicit guidance about when to use this tool versus alternatives. The closest is the claim that the attribution check is one a generic linter misses, which implies a comparative advantage but does not state when to choose this tool over sibling tools or what to use instead.

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

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

Annotations only say readOnlyHint and openWorldHint; the description adds substantial behavioral context: real Chromium, exact assertion, per-width reporting, named offending elements, the skipped status when Playwright is missing, and a guarantee that it never reports an unmeasured pass. This far exceeds the annotation baseline without contradicting it.

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 tight and dense: one sentence states the core behavior and reporting, and a short dependency note covers setup and failure mode. Every sentence earns its place, with the most important assertion front-loaded.

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

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

Given the rich input schema, output schema, and safety annotations, the description covers the remaining decision-relevant context: exact criterion, output behavior, dependency requirement, and skip semantics. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, with defaults and bounds documented for all six parameters, so the description does not need to repeat parameter details. The description contributes only a generic reference to 'a set of widths,' which does not add semantic value 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 states a concrete, specific behavior: load each page in headless Chromium and assert that scrollWidth does not exceed innerWidth. This precise scope clearly distinguishes it from the sibling check_* tools, all of which target different concerns.

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 makes the tool's context clear from its operation, but it never explicitly says when to prefer this tool over alternatives or when not to use it. No sibling comparison or exclusion is given, so usage guidance is mostly implied by the title and behavior rather than 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 signal read-only, idempotent, and closed-world behavior. The description adds value beyond these by explaining a key nuance: a second copy is treated as a second value even if it has not yet disagreed with the original. It also discloses how patterns work (presets vs. regex) and that anything outside presets becomes a regular expression. This extra context about interpretation and pattern handling goes beyond what annotations provide.

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

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

The description is well-structured with a clear lead sentence, an illustrative rationale, and parameter guidance. It is slightly verbose, but each sentence contributes value—explaining the tool's purpose, the reasoning behind it, and the behavior of key parameters. It front-loads the core function before diving into nuances, making it easy to scan.

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 complex tool with six parameters, the description covers the essential behavioral aspects: what it does, how it handles duplicates, how to restrict to a single source, default patterns, and the regex fallback. Since an output schema exists, the absence of return-format details is acceptable. Nothing critical is missing for an agent to invoke it 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 description coverage is 100%, so all parameters have basic descriptions. The description adds meaningful nuance: it enumerates the preset pattern names, explains that non-preset strings are regular expressions, and clarifies the intended use of source_of_truth (the one file allowed to hold values). This goes beyond the schema's terse descriptions, enriching the semantics for pattern-related and source_of_truth 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 clearly states the tool scans for values appearing in more than one file and reports them. The verb 'Scans' and 'reports' are specific, and the resource (values that are repeated across files) is well-defined. It even sets itself apart from sibling check tools (copy, honesty, assets) by focusing on duplication across files, making its purpose 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?

The description provides implicit usage guidance: it explains when to enforce the strict form via source_of_truth, and gives a real-world example to illustrate the problem it solves. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions. The context is clear enough for an agent to infer its primary use case, but not explicit about 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?

Beyond the readOnly and idempotent annotations, the description discloses that failures produce copy-pasteable fix commands and that no vague configuration suggestions are given. This sets accurate expectations for the tool's output and behavior.

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

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

Three short paragraphs, each adding distinct value: what is checked, what is printed, and when to run. The most important information is front-loaded, and there is 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?

This is a simple zero-parameter diagnostic; annotations cover safety, the output schema covers return shape, and the description covers invocation timing and output style. Nothing essential is missing for an agent to invoke it 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?

The input schema has zero parameters with 100% description coverage, so no parameter explanation is needed. The baseline of 4 applies because there is nothing for the description to add.

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 concrete verb ('Checks') and names exact subjects: Node, the optional headless browser, and Codex server registration. This clearly differentiates it from sibling site-audit tools like check_responsive and check_copy, which inspect site content rather than the local environment.

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 'Run this first whenever something does not work,' giving a clear when-to-use directive. It does not enumerate alternatives, but the run-first framing provides sufficient context for selecting this tool over siblings.

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

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

Annotations already establish read-only and idempotent behavior; the description adds useful behavioral context by explaining that omitting the id lists the rulebook and that filters narrow results. It does not mention pagination or freshness behavior, but the output schema and read-only annotation cover the main safety profile.

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 paragraphs with the main action front-loaded. The enumerated note contents are long but each item adds meaning, and there is no filler or restatement of the title.

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

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

For a read-only tool with no required parameters and an output schema, the description covers the main lookup mode, the list mode, and possible filters. The only real gap is the unresolved 'category' filter mention, and it could clarify how to choose among the optional arguments, but these are minor.

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

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

Schema description coverage is 100%, so the schema already documents the rule, tier, and search parameters. The description adds a useful 'part in square brackets' cue, but much of the no-id/list behavior is already present in the schema. The mention of 'category' as a possible filter does not match a schema property, so the description does not substantially exceed schema semantics.

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 concrete verb and resource: given a rule id, return the whole teaching note, and it enumerates what the note contains. It also clearly distinguishes the no-id rulebook-listing mode, so an agent can tell this lookup from the check/review sibling tools.

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

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

The description gives explicit invocation contexts: with a rule id from a review, with no id to list the rulebook, and with tier/search/narrowing filters. It does not explicitly name alternatives or exclusions, but the rule-id-from-review cue and unique resource make when-to-use clear.

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

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

Annotations provide no safety hints (all false), so the description must carry the burden. It discloses that it writes three files and that content is not invented, but it omits key side effects: it does not mention that it may overwrite existing files when force=true, that it refuses to write into a non-empty directory unless the files were tool-written, or that it writes to a local ledger by default. These behaviors are only in the parameter schema, not the description.

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

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

The description is front-loaded with the core action and then lists many specific design constraints. While the list is long, each item is a concrete rule an agent needs to know to scaffold a compliant site. It is structured into two coherent paragraphs with minimal fluff, though it could be tightened by moving some design details to a reference.

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 output schema exists, the description need not explain return values. It covers the main purpose and the design rules thoroughly, but it omits edge-case behavior (e.g., failure when directory is not empty, overwrite semantics) that are relevant to calling the tool correctly. For a scaffold tool with six parameters, a bit more operational context would help, but it is not severely 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 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond the schema—it never mentions 'hue', 'name', 'force', 'record', or 'directory' semantics. It does reference the ledger concept, but that maps to the 'record' parameter without naming it. No added value.

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: 'Write index.html, styles.css and NOTES.md into a folder.' The title 'Scaffold a site that passes the rulebook' reinforces the purpose. It clearly distinguishes from sibling tools like review_site or palette_from_subject, which are checks or helpers, not creators.

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 this is the tool to use when you need a new site that will pass review_site ('The page is built to come back clean from review_site'). However, it never explicitly states when to use it vs alternatives, nor does it mention prerequisites or workflow ordering (e.g., 'use palette_from_subject first to choose a hue'). The context is implied, not explicit.

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

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

Annotations already mark this as read-only, and the description adds useful behavioral context: stops are derived from the rulebook, cite rule ids, and are deliberately ordered for learning rather than fault detection. This goes beyond the safety hints and clarifies what the agent can expect from the content.

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 compact yet information-dense, with every sentence serving a purpose: defining the route, distinguishing it from review_site, explaining provenance, and giving usage guidance. It front-loads the core concept and avoids 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 an output schema present, a read-only annotation, and only two optional parameters fully documented in the schema, the description supplies all necessary context for correct use. It explains the ordering rationale, the relationship to review_site, and the stop-by-stop access pattern.

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 parameters are already well documented. The description adds a small clarification about passing a stop number, but it does not meaningfully extend the schema's explanation of the depth parameter.

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 explicitly defines the tool as a ten-stop learning path ordered by what a beginner needs first, and differentiates it from review_site's critique-oriented order. This gives a clear verb-resource relationship and makes sibling distinction immediate.

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 explicitly contrasts with review_site, stating that review_site's ordering is right for a critique and wrong for learning, which tells the agent when to use this tool versus that sibling. It also gives a direct usage instruction: pass a stop number to read one stop at a time.

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

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

Annotations already declare readOnlyHint and idempotent hints, and the description adds valuable behavioral detail: quantization approach, output contents, WCAG contrast computation, and explicitly that nothing is uploaded. This goes well beyond the annotations and gives an agent confidence about privacy and side-effect-free execution.

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 paragraphs with a clear progression: what it does, what it returns, and practical constraints (formats, privacy). Every sentence adds information, and the most important output characteristics are front-loaded.

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

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

For a tool with five parameters and an output schema, the description fully covers formats, algorithm behavior, output artifacts, and integration with init_site. Nothing an agent needs to decide whether to call this tool is missing, and the output schema handles return-value details.

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 fully documents count, image, algorithm, merge_similar, and sample_budget. The description adds some connecting context (median cut vs k-means, coverage information) but does not materially enrich parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description names a specific verb (quantises), a clear resource (image), and the exact output (palette with coverage, WCAG contrast matrix, token set). It is unambiguous about what the tool does and is easily distinguishable from siblings like palette_from_subject by the emphasis on photograph-derived palettes.

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 for when the tool is appropriate: extracting a palette from a photograph, with supported formats and a local-processing guarantee. It also offers algorithm-selection guidance (k-means for soft gradients) but does not explicitly state when to prefer this over palette_from_subject or other palette-related 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?

Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=true, so the safety and determinism are covered. The description adds extensive behavioral context beyond that: the specific color exclusions (banned indigos, no pure black/white), the neutral chroma band (0.005-0.015), hue stability between light/dark, the WCAG contrast matrix guarantee, and the provenance reporting (object vs hash). These are valuable behavioral traits not derivable from annotations or schema.

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

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

The description is moderately long but front-loaded with the core action and constraints. Each paragraph adds a distinct piece of information: the build process and color guarantees, the contrast matrix, and the provenance/alternative tool. It could be slightly tighter but avoids redundancy and every sentence serves a purpose.

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

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

Given the tool's complexity, the output schema (present but not shown) and annotations cover safety and determinism. The description covers everything an agent needs to decide when to use it and what to expect: the output (hex, contrast matrix, provenance), the constraints on colors and hue, and the explicit alternative. No critical information is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'anchor hue' and 'accent_chroma' but does not add meaning beyond what the schema already provides (e.g., the accent_chroma corpus band of 0.12-0.22 and default 0.16 are already in the schema description). No new parameter semantics are introduced.

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 ('builds a complete two-state palette') and resource ('from one anchor hue, in OKLCH, and emits hex'), and explicitly differentiates itself from the sibling palette_from_image by noting that the image-based tool is 'the stronger move' when a photograph exists. It also details what it cannot return, leaving no ambiguity about its function.

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 title and description both specify the condition for use ('when there is no photograph yet'), and the description explicitly names the alternative (palette_from_image) and advises using it when a photograph exists. It also explains the provenance behavior (object vs hash) and why image-based is better, giving clear when-to and when-not-to guidance.

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

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

The description goes far beyond the readOnly/idempotent annotations: it details the exact structure of each finding, the visitor-notice ordering, the chess-style annotation meaning, and the prominent handling of rules that could not run. It also states these are never counted as passes, which is a behavioral subtlety an agent must know.

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

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

The description is longer than the ideal minimal definition, but every sentence carries distinct information about output structure, ordering, failed-rule behavior, or follow-up guidance. The main purpose is front-loaded in the first sentence, and the rest is justified by 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 the tool's complexity, the description is thorough: it explains the output format, ordering principles, failure handling, and how to get deeper explanations. With a rich output schema, 100% parameter coverage, and clear annotations, nothing an agent needs to invoke review_site correctly is missing.

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

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

Schema description coverage is 100%, and the description does not add any parameter-specific meaning beyond what the schema already provides. The reference to using explain_rule with rule ids is the only parameter-related context, but that is a follow-up action rather than a semantic clarification of skip or focus.

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 opening sentence uses a specific verb-resource pair ('Read every page and stylesheet in a folder and return an annotated critique') and immediately scopes the action to the whole rulebook. This clearly distinguishes it from the sibling check-specific tools like check_copy or check_responsive.

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 title and description make clear this is the comprehensive whole-rulebook review, so the context for using it over per-check siblings is evident. It does not explicitly state when not to use it or name alternatives, but the 'whole rulebook' framing and the mention of using explain_rule as a follow-up provide solid situational guidance.

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