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

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat idempotency. It adds value by specifying the output includes WCAG 2.1 criteria, which goes beyond annotations. No contradictions.

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?

Single sentence that is front-loaded with the action and result. No unnecessary words; every part is relevant.

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 only two simple parameters, one required, and an output schema existing (not shown but indicated), the description is fully adequate. It explains what the tool does and what is returned.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds context that the foreground is checked against the background, but doesn't clarify hex format or that background defaults to white. Minimal 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 specifies the exact action ('Return WCAG 2.1 contrast ratios and AA/AAA pass/fail grades') and the resource ('foreground hex against a background'). It clearly distinguishes from sibling tools like accessibility_font or accessibility_matrix by focusing on contrast ratios.

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 no guidance on when to use this tool versus alternatives. Sibling tools include accessibility_matrix (which likely checks multiple contrasts), accessibility_simulate (simulations), and others, but there is no mention of when to choose this specific tool.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by detailing the output: ranked list, WCAG grades, and specific recommendations for body text, large text, and UI components. It provides behavioral context beyond the annotation, making the tool's non-destructive nature clear.

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 of about 25 words, front-loaded with input context. Every word earns its place, with no redundancy or 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's simplicity (2 required parameters, 100% schema coverage, output schema present), the description adequately covers input and output behavior. No additional details about edge cases or errors are necessary for a focused analysis tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description rephrases parameter names ('background hex', 'palette of candidate foreground colours') without adding new semantic meaning beyond the schema. It does not clarify formatting or units beyond what the schema 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's purpose: ranking foreground colours against a background hex using contrast ratios and WCAG grades, with specific recommendations for body text, large text, and UI components. It distinguishes itself from sibling colour tools by focusing on font/foreground contrast advice.

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

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

The description implies usage when needing contrast recommendations for foreground colours, but does not explicitly state when to use this tool versus alternatives like 'accessibility_check' or other colour comparison tools. No exclusion criteria or alternative references are provided.

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 provide readOnlyHint=true, so no contradiction. Description adds output behavior (returns combinations and grades) but does not disclose additional side effects or requirements beyond the read-only nature.

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 concise sentences, front-loaded with core functionality followed by usage guidance. No wasted 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?

Output schema exists, so return values need not be detailed. Description covers input, output, and usage guidance adequately for the tool's complexity.

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 description adding minimal context beyond the schema (e.g., that it computes combinations). 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?

Description clearly states the tool accepts a palette array and returns all foreground/background combinations with contrast ratios and pass/fail grades for AA/AAA standards. It also distinguishes from sibling tool 'accessibility_check' by recommending this tool for multiple checks.

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

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

Explicitly says to use instead of calling accessibility_check multiple times for a palette, providing clear context. No explicit when-not to use, but the sibling relationships imply it.

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 readOnlyHint=true, so the safe read operation is already clear. The description adds valuable context: it is deterministic, incurs no LLM cost, and lists the return content categories. This goes beyond 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 a single sentence with a colon separating the main action from details. It is front-loaded with the verb and resource, and every phrase adds value. No redundant information.

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

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

For a simple one-parameter tool with a clear input schema and an output schema present, the description sufficiently conveys what the tool does and returns. No additional details are needed.

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% (the 'palette' parameter already describes 'Array of hex values'). The tool description does not add additional meaning or usage constraints beyond that, so a 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 verb 'Convert' and the resource 'palette WCAG matrix into actionable design-system rules'. It lists specific outputs (safe pairs, AA-only pairs, etc.), distinguishing itself from siblings like accessibility_matrix (which generates the matrix) and accessibility_check (general check).

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

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

The description implies usage when a WCAG matrix is available and actionable rules are needed, and notes it is deterministic with no LLM cost. However, it does not explicitly state when not to use this tool versus alternatives like accessibility_check or accessibility_matrix.

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, but the description adds the specific color blindness model (Brettel-Vienot-Mollon), providing useful behavioral context beyond the annotation.

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 directly conveys the tool's purpose without extraneous information, making it highly concise and 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?

With a single required parameter, existing output schema, and clear annotations, the description covers the essential behavior. It mentions the model, which is a plus, though output format could be hinted for completeness.

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 a clear description for hex_val. The tool description does not further elaborate on the parameter format or constraints, so no additional value is added 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 clearly specifies the action (Return simulated hex values), the resource (hex values for protanopia, deuteranopia, tritanopia), and the model used, distinguishing it from sibling tools like colour_compare or accessibility_check.

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 minimal usage guidance. It does not explicitly state when to use this tool versus alternatives such as accessibility_check or colour_metrics, leaving the agent to infer context from the sibling list.

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 indicate readOnlyHint=true, and the description adds behavioral details: fetches archive palette, produces multiple outputs, handles locked_palette to skip archive query, and supports model-specific prompts. No contradictions.

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 paragraph that covers all essential aspects: purpose, outputs, supported models, example, and use case. It is concise but could be slightly more structured (e.g., bullet points for outputs).

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 and full parameter descriptions, the description provides complete context: what it generates, how it uses the concept, model options, and optional parameters. Nothing critical 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 coverage is 100%, but the description adds value by explaining the locked_palette behavior ('no archive query is run') and the overall workflow. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states the tool generates a 'complete colour direction package' for another AI, listing specific outputs (agent brief, colour tokens, prompts). It distinguishes from siblings by focusing on producing a brief for other AI systems, not just a palette or analysis.

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 an example (task='luxury hotel bedroom', concept='Ottoman winter luxury', model='midjourney') and states the tool's use case: 'make Colour Memory the colour layer for other AI systems.' However, it does not explicitly mention when not to use or contrast with similar tools like palette_generate.

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?

ReadOnlyHint annotation matches description. Description additionally details return metrics (fidelity score, dE2000, match quality, verdict), providing rich behavioral context beyond what annotations offer.

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?

Single paragraph, front-loaded with purpose, then usage, then output. Every sentence adds value 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?

Given 3 parameters and an output schema, description covers all aspects: what it does, when to use, inputs, outputs, and workflow integration. No gaps.

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

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

Schema has 100% coverage, but description adds meaning by linking target_palette to agent_brief colour_tokens and explaining image_url/image_base64 as alternatives. Also summarizes output, though output schema exists.

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?

Description uses specific verb 'verify' and resource 'colour fidelity', clearly distinguishing from sibling tools like colour_compare or palette_verdict. States exactly the inputs and outputs.

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 says 'Use after agent_brief + image generation to close the colour loop', giving clear context for when to invoke. Does not exclude alternatives or mention when not to use, but implied by the workflow.

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 readOnlyHint=true; the description adds further transparency by stating 'No Claude call — pure archive data analysis' and detailing all returned metrics, which goes beyond 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 two sentences, front-loaded with the core action, then lists outputs and usage cases. Every sentence adds value; no 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 an output schema exists and the description already covers key return fields and usage, the definition is fully complete for an agent to use effectively.

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 a clear description for the archive parameter. The description reinforces that the tool works on 'any named archive' and provides examples in the schema, adding value without redundancy.

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 it runs a data quality audit on an archive, listing specific metrics returned (entry count, health score, grade, issue counts) and noting it's pure analysis with no Claude call, distinguishing it from sibling tools like archive_status or archive_search.

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 explicit usage scenarios: before building new archive content or after a batch import. It does not explicitly list alternatives or when not to use, but the context is clear enough for an agent.

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

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

Annotations indicate readOnlyHint=true, and the description adds context about searching an archive and generating content via Claude. It discloses the tool's behavior without contradiction, though it could mention that no data is mutated.

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, with two paragraphs front-loading the purpose and an example. Every sentence contributes meaning, though it could be slightly more compact.

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's coverage of the tool's input and output (one-liner, short story, tweet) is adequate. It omits edge cases but is sufficient for typical creative 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 schema has 100% coverage, and the description adds value by explaining how parameters work together (e.g., concept and expected_colour) with examples. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: find the most surprising archive colour for a concept and generate a memorable one-liner subverting expectations. It uses specific verbs and resources, and the unique focus on subverting clichés distinguishes it from sibling tools like colour_story or colour_strategy.

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: public-facing demos, content, and brand storytelling. It includes an example but does not explicitly state when not to use or compare to alternatives, though the context is sufficient for most agents.

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, so no destructive actions. The description adds value by detailing the output structure (coverage matrix with entries, grade, best match, source type needed) and the behavioral purpose of identifying gaps before report building. No contradiction.

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 sentences, front-loaded with the main purpose. The second sentence is dense but well-structured, covering output and usage without fluff. Efficient and clear.

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 2 parameters (1 required), no enums, and an output schema present, the description provides good context. It explains the output and usage sequence, which is sufficient for the tool's complexity.

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 both parameters described. The description adds a concrete example for 'themes' ('opium, gin, gambling, racing') and notes 'archives' is optional, which matches schema. This adds minor value but doesn't significantly extend 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 clearly states the tool's function: given themes, report evidence coverage. It specifies the output (coverage matrix with entries, grade, best match, source type) and distinguishes from sibling tools by stating it should be used before archive_report_brief or brief_forensic.

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 says 'Use this BEFORE building an archive_report_brief or brief_forensic to know where the evidence is strong and where gaps will appear.' It also explains the benefit: preventing building reports that ignore gaps. While it doesn't explicitly list when not to use, the usage context is very 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?

Discloses detection logic and returns risk scores, safe phrasing; consistent with readOnlyHint annotation. Adds context 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?

Two sentences, front-loaded with action, then outputs and example. No wasted 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?

All required aspects covered: purpose, inputs, outputs, usage context, and safety. No gaps given schema and annotation richness.

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%; description adds logical meaning by explaining how parameters relate to anachronism detection, enhancing understanding beyond 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 clearly states the tool checks colour entries for anachronism risk, detecting source date mismatches and modern archives, with a concrete example differentiating it from 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 implies when to use (historical documents) via an example, but does not explicitly exclude alternatives or specify when not to use.

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 declare readOnlyHint: true, so the description is not required to state read-only. The description adds behavioral context: it treats absence of evidence as a forensic finding, not an invitation to invent. This goes beyond annotations and helps the agent understand its defensive role against hallucination.

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 (approx. 90 words), front-loaded with the core purpose and output structure. Every sentence is informative: definition, example, use cases. No redundant or filler content.

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

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

Given the tool's moderate complexity (4 params, 2 required) and the presence of an output schema, the description provides complete context: input examples, output fields enumerated, and use case scenarios. Agent can confidently select and invoke this 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?

Input schema covers all 4 parameters with descriptions (100% coverage). The description supplements with realistic examples (e.g., '#4A535C', 'cyanosis in a death chamber', 'DarkHistory', default n_candidates=5), which adds semantic clarity beyond the schema definitions.

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 states the tool's purpose: given a hex color and a proposed claim, it returns archive support level, missing evidence, required source type, and safe agent wording. It distinguishes itself from sibling tools by framing as an anti-hallucination endpoint for evidence gap analysis.

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 a concrete example and lists relevant workflows (museum, documentary, editorial, legal, forensic), clearly indicating when to use. However, it does not explicitly state when not to use or contrast with similar siblings like archive_search or archive_audit.

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, so the read-only nature is known. The description adds behavioral context by detailing the output structure (claim, evidence type, source specificity, etc.) and the separation of documented fact, inferred, and interpretive elements. This enriches transparency beyond the annotation alone.

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

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

Three sentences plus a short key phrase. The description is front-loaded with the core function in the first sentence. Every sentence adds value: purpose, output specifics, and usage guidance. No wasted 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?

The tool is simple (1 param, output schema exists). The description comprehensively covers what the tool does, what it returns (specific fields), and its role as the trust endpoint. It mentions hex status and citation format, leaving little ambiguity. With an output schema, return details are not needed, and the description effectively completes the picture.

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 a clear description of the single parameter 'colour_name' and examples. The tool description does not add new semantic information about the parameter beyond the schema; it focuses on the tool's function. Baseline 3 is appropriate as the schema already does the work.

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

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

The description clearly states the tool explains provenance of a named archive colour with explicit separation of fact, derivation, and interpretation. The verb 'Explain' and resource 'provenance' are specific. It distinguishes from siblings like colour_story or colour_forensics by positioning itself as the 'trust endpoint' for provenance, making its purpose unique.

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 identifies the tool as 'the trust endpoint' for colour data provenance and says it's 'Essential for any use case requiring intellectual honesty about colour data provenance.' This provides clear context for when to use it, but it does not explicitly state when not to use or name alternatives, so a slight gap exists.

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 indicate readOnlyHint=true, and the description appropriately confirms no side effects. It adds transparency about the tool making 'Two Claude calls total', which is beyond annotations, and details the comprehensive output format.

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 purpose and lists inputs and outputs. It is efficient but could benefit from structure like bullet points for clarity. Still, it is concise given 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 complexity (7 params, output schema exists), the description covers inputs, outputs, usage context ('first for any document workflow'), and contrasts with siblings. It is complete and leaves no major gaps.

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

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

Schema coverage is 100% with detailed descriptions for all 7 parameters. The description lists the same parameters (title, audience, themes, etc.) but adds no new meaning beyond what the schema 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 clearly states it is a 'complete archive research package' for documents, PDFs, or briefs, with specific verbs like 'archive research' and outputs like color cards. It distinguishes itself from sibling tools by explicitly naming the tools it replaces (archive_search, get_colour_card, cliche_breaker, agent_brief).

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 says 'Use this first for any document workflow' and explains it replaces chaining multiple tools, providing clear guidance on when to use this tool versus 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 indicate read-only behavior (readOnlyHint: true). The description adds transparency about the result format: it can return 150-character snippets or full notes depending on the 'include_full' parameter, and it clarifies search scope (names and notes). This adds useful context beyond 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 two concise sentences that efficiently convey the core action, scope, and complementary relationship to a sibling tool. Every sentence adds value 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?

Given the complexity (7 parameters, output schema exists, annotations present), the description is complete: it covers purpose, result format, relationship to sibling, and key parameters. The output schema handles return values, so no further detail needed there.

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?

All 7 parameters have descriptions in the input schema (100% coverage), so the schema already provides good meaning. The description adds minimal extra parameter-level detail mostly repeats the search categories. 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 clearly states the tool performs full-text keyword search across archive colour names and notes, and lists specific types of queries (name fragment, material, cultural reference, etc.). It explicitly distinguishes itself from a sibling tool (conceptual embedding search) by specifying exact keyword matching, making the purpose distinct.

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 mentions that this tool complements conceptual embedding search with exact keyword matching, providing clear context for when to use it. However, it does not explicitly exclude other usage scenarios or mention when-not-to-use, missing a chance for fuller guidance.

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

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

Annotations already declare readOnlyHint=true, so the description's claim of returning live status is consistent. The description adds value by listing what is returned, but does not disclose additional behavioral traits beyond the annotation.

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, well-structured sentence that front-loads the core action and lists specifics without any extraneous information.

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

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

For a zero-parameter, read-only status tool with an output schema, the description fully covers what the tool returns (six items). No gaps are apparent.

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 no parameters, and schema coverage is trivially 100%. With no parameters, the description need not add parameter meaning; baseline 4 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 tool's purpose: 'Return live archive status' and enumerates specific items (total colour count, per-archive breakdown, embedding model, search engine state, API version). This distinguishes it from sibling tools like archive_audit or archive_search.

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

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

The description implies usage when archive status is needed but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the deterministic nature disclosed in the description adds value. The statement 'No LLM cost' provides additional transparency about cost and behavior beyond the annotation, though more detail on output stability would strengthen this.

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 that front-load the most important information: what the tool returns and key behavioral traits (deterministic, no cost). No filler 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?

Given the complexity (multiple outputs) and the presence of an output schema, the description covers the main outputs but could briefly mention the expected structure or format. However, the reliance on the output schema for details makes this acceptable.

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 descriptions for all 5 parameters. The description does not add new meaning beyond the schema, but the schema is already sufficient. No parameter-specific elaboration is present, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Complete brand asset pack' and lists specific outputs (CSS variables, Tailwind config, Figma tokens JSON, citation cards, Markdown brand guide). It distinguishes itself from siblings by being a comprehensive export, not a single analysis or audit 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?

No explicit when-to-use or when-not-to-use guidance is provided. While the description implies it's for final shipping, it doesn't differentiate from similar sibling tools like palette_export. The 'Deterministic. No LLM cost.' hints at safe repeated use but lacks context on 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. The description adds that 'All computed data -- no LLM cost', which is a behavioral trait not in annotations. It does not contradict annotations or hide important traits like data modification.

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 (4 sentences) and well-structured: purpose first, then parameters, then outputs, then usage note. No filler or 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?

Given the tool's complexity (5 parameters, output schema exists), the description covers all key aspects: inputs, outputs (colour roles, WCAG matrix, cultural risk, verdict, CSS, Tailwind, production notes), and behavioral context (no LLM cost, replaces chaining). With output schema present, return values are sufficiently explained.

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%—all 5 parameters have descriptions in the schema. The description restates the parameters but adds no new semantic meaning beyond stating what the tool accepts. 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 clearly specifies the tool's action ('Complete brand colour intelligence audit') and the resource ('brand'). It distinguishes itself from siblings by stating it replaces chaining multiple separate tools (accessibility_matrix, cultural_risk_assessment, palette_verdict).

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 states when to use this tool ('in one call' vs chaining separate tools) and what to do with results ('Pass results to an LLM for written narrative'). It implies not to use if you need only one component, but doesn't explicitly say when not to use it.

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 indicate readOnlyHint=true, and the description details the non-destructive output (distances, scores, verdicts). It adds context beyond annotations by describing what is returned and the analytical process. No contradictions detected.

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 focused paragraph that lists inputs and outputs efficiently. It is concise with no fluff. Could be slightly improved by separating input/output sections or using bullet points, but current structure is effective.

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 presence of an output schema, the description adequately covers purpose, inputs, and key outputs. It explains the tool's value and use case. With 6 parameters and rich return data, the description provides sufficient context for an AI agent to use the 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 coverage is 100%, but the description clarifies that competitor_hexes and competitor_names must match order, which is not explicit in the schema. It also enumerates output components, adding value. The description slightly enhances understanding of parameters 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 explicitly states the tool's purpose: checking if a brand can own a colour against competitors. It specifies inputs and outputs, and the title 'Brand Colour Collision Check' reinforces this. The tool is clearly distinguished from sibling tools which cover other aspects of colour analysis like cultural risk or forensics.

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 advises use before committing to a brand colour in a competitive market, and mentions it replaces manual colour distance checks. While it doesn't explicitly list when not to use it, the context is clear. It could be improved by directly comparing to siblings like 'colour_cultural_risk' or 'colour_forensics', but current guidance 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?

Annotations already indicate readOnlyHint=true. The description adds valuable behavioral context: 'runs entirely internally -- no chained calls, cannot be blocked by agent safety filters' and mentions 'Two Claude calls total'. This goes beyond annotations, though it could detail what 'internal' means.

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

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

Two dense sentences cover purpose, inputs, outputs, usage guidance, and behavioral details. Front-loaded with 'one-call complete'. No 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?

Given the complexity (7 params, nested objects, many siblings, output schema exists), the description covers purpose, usage, safety, and output list comprehensively. Could mention that output schema is defined 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?

Schema description coverage is 100%, so baseline is 3. The description lists input parameters but does not add new semantics beyond the schema. However, it lists output components which indirectly contextualize inputs.

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 'one-call complete brand colour intelligence report' and lists both inputs and outputs. It explicitly distinguishes itself from sibling tools like colour_strategy, cliche_breaker, etc., by saying 'use this instead of chaining...'.

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 tells when to use the tool (instead of chaining multiple individual tools) and provides a clear context. It does not give explicit when-not-to-use scenarios, but the alternative is implied.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds behavioral context: 'Deterministic. No LLM cost,' indicating predictable output and no cost implications, which is valuable 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 two sentences, front-loaded with the core purpose ('Complete brand colour system in one call'), followed by a concise enumeration of outputs. Every sentence adds value with no 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 the tool has an output schema (though not provided here), the description sufficiently explains what the tool returns. It covers the key outputs and behavioral traits (deterministic, no LLM cost). With good annotations, completeness is high.

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 5 parameters have basic descriptions (e.g., 'Hex values', 'Target market e.g. global, UK, Japan'). The tool description adds no extra meaning beyond these schema descriptions, so a baseline of 3 is appropriate.

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

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

The description clearly states it returns a complete brand colour system with specific outputs like colour roles, light/dark mode maps, typography guidance, etc. The phrase 'Complete brand colour system in one call' differentiates it from other colour tools that may be more specialized, though it does not explicitly contrast with siblings.

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

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

The description implies use when a comprehensive colour system is needed ('Complete brand colour system in one call'), but does not explicitly state when to use this tool versus alternatives like colour_card or palette_generate. No exclusions or conditions are provided.

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 declare readOnlyHint=true, and the description aligns with that by describing a read operation. It adds useful behavioral details about the return fields (hex, archive, provenance, cultural notes) beyond the annotations, providing a clear picture of what the tool returns.

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, concise sentence (16 words) that front-loads the tool's purpose. There is no extraneous information; every word adds value.

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 that an output schema exists, the description appropriately identifies the key return fields. While it doesn't cover error cases or edge conditions, the tool is straightforward and the description provides sufficient context for typical 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?

Schema coverage is 100%, but the description adds significant value by providing examples for both parameters and indicating that the slug parameter is preferred for reliable retrieval, which guides the agent in parameter selection.

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 ('Look up'), the resource ('named colour'), and the expected output (hex, archive, provenance, cultural notes). It distinguishes itself from sibling tools like colour_combination or colour_compare by focusing on retrieving details for a single colour by name.

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

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

The description does not provide any guidance on when to use this tool versus the many sibling colour tools, nor does it mention when not to use it or alternative approaches. Users are left to infer the appropriate context.

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, so the read-only nature is covered. The description goes beyond by specifying output components (harmony, clash warnings, etc.), adding value without contradicting 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?

Single sentence that is front-loaded with the verb 'Assess', followed by clear input and output specification. No wasted 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 combination analysis tool with an output schema, the description adequately covers input, context, and high-level output. It provides enough information for an agent to understand what the tool does without being overly verbose.

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 parameter descriptions. Description reinforces the input count (2-5) and context options but does not add substantial new meaning beyond the schema, 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?

Description clearly states the tool assesses 2-5 colors as a combination for a given context and lists specific return values (harmony type, clash warnings, contrast summary, deployment rules). This distinguishes it from sibling tools like colour_compare or colour_harmonies.

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

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

The description implies usage for combination assessment per context but does not explicitly state when to use this tool versus alternatives or provide exclusions. It gives context but lacks direct guidance on 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 declare readOnlyHint=true, and the description adds detailed behavioral context about what is returned (quantified differences, cultural context, comparisons). No contradictions; description enriches understanding of tool behavior beyond 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 efficient but the first sentence is dense with information; could be slightly more structured. However, key points are front-loaded and no words are wasted.

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 complexity of the tool (perceptual and cultural comparison), the description covers inputs, outputs, usage guidance, and behavioral caveats. An output schema exists, so return values are further documented. The description is fully complete for an agent to select 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% with descriptions for both hex parameters. The tool description adds no additional meaning beyond the schema, so 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 uses specific verbs ('deep perceptual and semantic comparison') and resource ('any two hex values'), and lists concrete outputs (LRV, chroma, hue angle, etc.). It clearly distinguishes from sibling tools by stating it is not a harmony tool but a decision and reasoning 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?

Explicitly states when to use ('choosing between two colours or explaining why one works better') and when not to ('Not a harmony tool'), providing clear context for selection among sibling tools.

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

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

Annotations indicate readOnlyHint: true, and the description aligns with this. The description adds behavioral details: returns warnings, positive associations, context-dependent readings per colour family, and specific market flags. It discloses the tool's foundation on documented associations. No contradictions.

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, consisting of two sentences that front-load the functionality and then provide usage guidance. Every sentence adds value with no extraneous information.

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

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

The description adequately covers what the tool does, what it returns, and when to use it, especially given the presence of an output schema (not shown but noted). It mentions the basis of associations, which adds trust. Minor omission: no mention of limitations or example scenarios, but overall 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 description coverage is 100%, with each parameter having a clear description. The tool description adds context by explaining the overall purpose of the parameters (e.g., 'Score a hex value or palette' and 'Optional market focus'). However, it does not add significant new meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Score a hex value or palette for cultural sensitivity, symbolic weight, regional taboos, religious associations, and potential misinterpretation across global markets.' It specifies the verb 'Score' and the resource 'cultural risk of a colour or palette,' and differentiates from sibling tools like colour_harmonies or colour_forensics by focusing on cultural risk.

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: 'Use before deploying a colour in a global brand, product, or campaign context.' It also notes the basis is documented associations, not generalization. However, it does not explicitly mention when not to use it or suggest alternatives, which would strengthen the guidance.

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

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

Annotations provide readOnlyHint=true. Description adds that it uses 'pure archive and physics data,' is fast and cacheable, and has no Claude call, providing behavioral context beyond the annotation.

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 sentences, each serving a distinct purpose: core function, output list, backend nature, usage guidance. No redundant or filler content.

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

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

Given the output schema exists, the description need not cover return values. It lists all key output fields adequately. Single parameter and clear outputs make it 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 coverage is 100% for the single 'hex' parameter. Description provides an example format ('#4A2A50'), adding value over the schema description.

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 it returns a compact semantic fingerprint for any hex colour, listing specific output fields. It distinguishes from siblings like colour_story or colour_metrics by emphasizing semantic reasoning without long prose.

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 states when to use: 'when an agent needs to reason about a colour semantically without reading long prose' and 'ideal for filtering, ranking, or comparing colours.' Also notes it's fast and cacheable, without a Claude call.

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 discloses detailed behavioral traits: it returns a verdict, risks, required actions, light behaviour under three illuminants, substrate notes, and alternative recommendations. It also mentions the underlying methods (CIEDE2000 and Claude material knowledge). This adds significant value beyond the readOnlyHint annotation, which only indicates no side effects.

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 (~80 words), front-loaded with the core purpose, and efficiently lists outputs and examples. Every sentence adds value without redundancy, making it easy for the agent to parse quickly.

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 (5 parameters, including context like orientation and use), the description comprehensively covers what the tool does, why, and what it returns. The presence of an output schema (mentioned) further reduces the need for additional description about return values.

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 100% description coverage, with clear descriptions for all 5 parameters. The description reinforces these with example substrate values but does not add new meaning or constraints beyond what is already in the schema. 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 tool assesses hex colour safety for physical applications, with a specific verb ('Assess') and resource ('hex colour'). The title 'Colour Specification Safety Check' reinforces this. The list of outputs and examples (e.g., ultramarine on lime plaster) further clarify its purpose and distinguish it from sibling tools like colour_card or colour_compare.

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 the tool is used when assessing safety of a hex colour for physical application, and provides concrete examples of use cases. However, it does not explicitly state when not to use it or mention alternative tools, which would strengthen guidance for the agent.

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

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

Annotations already declare readOnlyHint=true, and description's 'Return...harmonies' is consistent. The description adds context about using 'named archive colours', which is helpful beyond 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?

Single sentence with no extraneous words. Every part is necessary and 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 tool's simplicity and the presence of output schema (handling return values), the description is sufficient. It covers what the tool returns and that it's based on archive colours. Could optionally mention that hex is required, but with one required param it's clear.

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 descriptions for both params. Description adds value by listing the specific harmony types (complementary, triadic, etc.), clarifying what 'harmony_types' can include, which goes beyond the schema's generic 'Harmony types to include'.

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?

Description uses specific verb 'Return' and resource 'complementary, triadic, analogous, and split-complementary harmonies', clearly distinguishing it from sibling colour tools like colour_combination or colour_compare.

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?

Description implies usage for getting harmonies matched to archive colours but offers no explicit when-to-use or when-not-to-use guidance, nor alternatives among the many colour-related 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?

The description adds valuable context beyond the readOnlyHint annotation: it reveals that the output is backed by the nearest archive colour's cultural provenance, and that audience and tone parameters tune the output. This helps the agent understand the data source and customization capabilities.

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 with zero waste. The first sentence front-loads the primary action and outputs, the second adds provenance context, and the third lists use cases. 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?

Given the tool's complexity (generating multiple content types with tunable parameters) and the existence of an output schema, the description is complete. It covers inputs, outputs, use cases, and behavioral context without needing to repeat return format 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?

With 100% schema coverage, the baseline is 3, but the description adds significant meaning: it explains how audience and tone are tunable with examples, and lists the specific outputs (hook, story, tweet, etc.) that the agent can expect. This goes well beyond the schema's parameter descriptions.

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

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

The description clearly states the tool generates multiple types of content (hook sentence, story, tweet, image prompt, follow-up questions) for any hex colour. It uses specific verbs and distinguishes from sibling tools like colour_story or colour_forensics by focusing on shareable content generation.

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 lists use cases: 'make archive colours shareable, to generate content, or to power a public-facing colour chat experience'. It provides clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative 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 indicate readOnlyHint=true, and the description aligns with a read-only operation. It adds context about brands but does not detail error handling or result ordering, which is acceptable given 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 a single sentence with no filler, front-loading the key action and brands concisely.

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 sufficiently covers the tool's purpose. It could mention default n=3 or multiple matches, but overall is very good.

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 description adds marginal value beyond the schema by mentioning the brands, but does not elaborate on the n parameter or hex_val format beyond what is in 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 clearly states the verb 'Find' and the resource 'nearest named colour in commercial paint systems', and distinguishes from sibling tools like colour_namer by specifying paint brands such as Farrow and Ball and Little Greene.

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

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

The description implies usage for matching hex colors to paint brand names but does not provide explicit when-to-use, when-not-to-use, or alternatives like colour_namer for generic color naming.

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?

Description adds value beyond readOnlyHint annotation by specifying exact metrics and illuminant conditions. No contradictions.

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?

Single sentence, front-loaded with purpose, lists metrics efficiently. No wasted 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?

Good for a single-parameter tool with output schema. Could mention error handling for invalid hex, but not essential.

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?

100% schema coverage; description repeats hex format but adds no extra meaning or validation details.

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

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

Clear verb+resource: 'Return perceptual colour metrics'. Specific metrics listed (LRV, chroma, hue angle, etc.) distinguish it from sibling tools like colour_card or colour_compare.

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

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

No guidance on when to use this tool versus alternatives. Siblings include many colour tools, but description does not help agent decide.

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 indicate readOnlyHint=true, but the description adds that the tool uses 'perceptually modelled subtractive mixing in CIE Lab space', which is not inferable from annotations alone. This provides valuable behavioral context beyond the safety hint.

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

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

Three sentences that are directly informative, no fluff. Key information is front-loaded: purpose, model, output, and an illustrative example. Every sentence adds value.

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 (handling return values) and the parameters are well-documented, the description covers the tool's purpose, model, example, and behavioral characteristics sufficiently for an agent to understand and 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?

Input schema already describes all three parameters with 100% coverage, including hex_a, hex_b, and ratio. The description adds an example (Prussian Blue and Yellow Ochre) but does not provide additional semantic nuance beyond the schema, so a 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 it simulates subtractive mixing of two colors in CIE Lab space, returning a mixed hex value and the nearest archive match with cultural context. It distinguishes itself from 'RGB screen blending', making its purpose specific and 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 explains what the tool does but does not explicitly state when to use it versus sibling tools like colour_combination or colour_harmonies. An agent lacks guidance on choosing this tool over others in the same domain.

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 aligns with the readOnlyHint annotation, adding context about archive verification and naming styles. No contradictions, but it doesn't delve into potential edge cases or side effects beyond the archive feature.

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 succinctly convey purpose, key features, and use case. No fluff, front-loaded with action and resource.

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 a complete schema, annotations, and output schema present, the description covers the core functionality and primary use case. It could mention output format or error handling but is sufficient for typical 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?

Schema coverage is 100% and description adds minimal extra meaning beyond what the schema provides (e.g., 'Choose from naming styles' is already implied by the style parameter description). 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 verb (generate), resource (colour names), and scope (archive-verified, for any hex value). It distinguishes itself from siblings like 'ecommerce_namer' by emphasizing archive grounding and Shopify product naming use case.

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 indicates usage for product naming in Shopify with archive-backed names and gives style options. However, it does not explicitly exclude alternatives or state when not to use it, leaving room for improvement.

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 declare readOnlyHint=true, so the description's job is lighter. It adds context by mentioning 'Archive-grounded name source with dE2000 distance', but does not elaborate on any behavioral traits like performance, required prerequisites, or what happens with invalid hex values. No contradiction with 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 two sentences long, with the first sentence front-loading the core purpose ('Return every developer token format') and listing examples. The second sentence adds relevant context about the naming source. No 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 tool with two parameters, full schema coverage, an output schema, and annotations, the description adequately explains what it returns and the source of names. It could be slightly improved by noting that the output schema provides the actual structure of returned token formats, but it is already quite 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 description provides little additional meaning beyond the schema. The 'hex' parameter is already described as 'Hex value e.g. #D4A829' in the schema, and the description does not add syntax or format details. The 'archive' parameter is merely called 'Optional archive filter' without further clarification.

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 returns 'every developer token format for a hex value', listing specific formats (CSS variable, kebab-case, etc.). It uses a specific verb ('Return') and resource ('developer token formats'), and distinguishes itself from sibling colour tools by focusing on token naming conventions.

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

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

The description implies usage for generating token formats from a hex value, but provides no explicit guidance on when to use this tool versus alternatives (e.g., other naming tools like colour_namer) or when not to use it. No exclusions or alternative tools are mentioned.

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 declare readOnlyHint=true, and the description is consistent with a read-only operation. The description adds context about the narrative covering cultural journey, history, civilizations, and archive names, which goes beyond the annotation.

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: two sentences plus an example, front-loaded with the core purpose, and every sentence adds value. No 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?

The description explains the return value (rich narrative about cultural journey, history, civilizations, archive names) and usage contexts. Given that an output schema exists, the description 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?

Both parameters (hex, n_archives) are fully described in the schema with descriptions. The description provides an example hex value and explains what the tool does, but does not add significant meaning beyond the schema for the parameters themselves.

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 returns a rich narrative about a color's cultural journey given a hex value. It specifies the verb (returns), resource (cultural story of a colour), and distinguishes from siblings like colour_dna, colour_forensics, etc., which focus on different aspects.

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 mentions the tool is essential for image generation prompts, brand storytelling, and creative briefs, indicating when to use it. However, it does not explicitly state when not to use it or contrast with similar siblings, leaving some ambiguity.

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 indicate readOnlyHint=true; the description adds valuable context about the tool's scope and outputs, enhancing transparency beyond the annotation.

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, starting with purpose, then listing inputs and outputs, and ending with examples. Every sentence is informative and necessary.

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 thoroughly covers the tool's purpose, all inputs with examples, and expected outputs. Given the complexity and presence of an output schema, it is fully 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?

The description adds meaning by grouping inputs (hex, brand_context, constraints, markets, medium) and providing examples, which goes beyond the schema's individual descriptions.

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

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

The description explicitly states it is the 'flagship commercial endpoint' that combines multiple analyses (archive, verdict, brand fit, etc.), clearly distinguishing it from sibling tools like colour_verdict or colour_cultural_risk.

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 context for when to use this tool (for a comprehensive strategy), but does not explicitly state when not to use it or list alternative tools.

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

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

Annotations already declare readOnlyHint=true, and description confirms a read operation by describing historical tracing. Adds context about chronological order and example but does not disclose any additional behavioral traits (e.g., data sources, limits).

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

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

Four sentences, each adding value: core action, elaboration, importance statement, and illustrative example. Front-loaded with key task, no filler. Within typical length guidelines.

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 low parameter count, presence of annotations, and existence of output schema, the description covers purpose, value, and an example. Slight gap: no mention of the scope of historical data (timeline length, cultures covered), but overall adequate for a straightforward lookup 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 description coverage is 100%, so baseline is 3. Description adds an example of usage but does not significantly enhance parameter meaning beyond what the schema already provides (hex field description, tolerance default).

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?

Description uses specific verb 'traces' and resource 'colour's appearances across cultures and centuries in chronological order', clearly distinguishing from siblings like colour_story by emphasizing chronological order and historical depth. Includes a concrete example (deep blue) that reinforces the purpose.

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?

Description says 'Essential for understanding why a colour carries the weight it does', implying usage context but does not explicitly state when to use this versus alternatives like colour_story or colour_forensics. No when-not-to-use or exclusion criteria provided.

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, so the agent knows it's safe. The description adds behavioral details about what is returned (historical variants, lighter/darker, cultural siblings), which enriches the context beyond the annotation.

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 waste: first sentence states the function, second provides a usage hint. 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?

Given the single required parameter and presence of an output schema, the description fully explains what the tool returns and when to use it. No gaps remain.

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%: the only parameter 'name' has a clear description in the schema. The tool description does not add additional parameter semantics, so a 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 uses a specific verb 'return' and clearly states the resource types: historical variants, lighter/darker versions, archive matches, and cultural siblings. It distinguishes its purpose from sibling colour tools, though it does not explicitly name alternatives.

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 statement 'Essential for designers exploring around a colour' implies the use case but does not provide explicit guidance on when to use this tool over siblings or when not to use it.

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 explains the tool returns a verdict with strengths, risks, avoid-if scenarios, and alternatives, backed by archive matching and AI. This adds behavioral context beyond the readOnlyHint annotation, which is consistent. No contradictions.

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 sentences plus a list of examples, efficiently conveying the core function and context. The examples are helpful but could be integrated more seamlessly; still concise overall.

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 presence of an output schema and moderate complexity (5 params, 2 required), the description covers all necessary aspects: purpose, inputs, outputs with verdict components, and backing technology. It is fully 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?

Schema coverage is 100%, so the description does not need to compensate. The provided examples of use_case values add marginal value beyond schema descriptions, but the baseline is met.

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 evaluates a hex color for a specific use case, market, and medium, returning a decisive verdict. It provides concrete examples, distinguishing it as a targeted evaluation tool among siblings.

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

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

The description implies usage through examples (e.g., luxury hotel brand) but does not explicitly state when to use this tool over siblings or when not to use it. More explicit guidance on alternatives would improve clarity.

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 declare readOnlyHint=true, consistent with reading/generating content. The description adds behavioral context by listing the components of the output package (palette, narrative, matches, etc.) and noting it's a one-call compound 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 concise with three sentences, front-loaded with purpose, and contains no unnecessary words. Every sentence adds value.

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 (compound, 7 parameters, output schema exists), the description is complete: explains purpose, usage, and outputs. The presence of an output schema means return values are 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 coverage is 100% so each parameter already has a description. The description adds high-level context but does not significantly expand on parameter meanings beyond what the schema 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 as a compound tool that takes a concept, medium, audience, and constraints to produce a complete design package. It distinguishes itself from siblings by explicitly replacing chaining of multiple individual 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?

Explicitly states when to use: 'Use when an AI agent or user needs a complete, deployable colour direction in a single call.' And when not: 'Not for iterative refinement — use individual tools for that.' Provides clear context and 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?

The description adds valuable behavioral context beyond annotations: it grounds copy in archive provenance, avoids generic AI output, and derives color names from historical matches. This aligns with the readOnlyHint annotation (no data modification).

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 efficiently structured: purpose statement, input/output list, unique value proposition, examples. Every sentence adds value, though minor trimming could improve conciseness.

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 (not shown but declared), the description covers the tool's purpose, inputs, outputs, and unique value. No missing elements for a read-only content generation tool.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description reiterates the input types but does not add significant new semantics beyond the context of archive grounding.

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 ('generate') and resource ('complete ecommerce product copy for any colour'), clearly distinguishing from sibling tools like ecommerce_namer. It lists inputs and outputs, 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 provides clear context for when to use (generating ecommerce copy for any color with archive provenance). However, it does not explicitly state when not to use or suggest alternatives, though the sibling tool ecommerce_namer implies a boundary.

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 adds significant behavioral context beyond the readOnlyHint annotation: it states names are archive-sourced, not invented, and include source citations. It details output fields (archive name, citation, description, dE distance, match quality, confidence), fully disclosing 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?

The description is well-structured with two sentences and bullet points, front-loading the core purpose. The bullet list of style options is slightly redundant with the schema's 'style' description but still useful.

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

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

Given 5 parameters, a rich output schema, and the need for defensible naming, the description covers all aspects: inputs, outputs, use cases, and behavioral guarantees. It is fully complete for agent decision-making.

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%, but the description adds context: hexes array format, style enumeration (geographical, poetic, etc.), and default max_dE (25). This enriches the schema without redundancy.

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 it generates archive-grounded colour names for up to 40 SKUs, specifying inputs and outputs. It distinguishes from sibling 'colour_namer' by emphasizing archive sourcing and defensible citations for ecommerce contexts.

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 lists use cases (paint, candle, fashion, homeware, cosmetics) and style options, providing clear context. However, it does not mention when not to use or compare to alternatives like 'colour_namer'.

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 discloses important behavioral traits beyond the readOnlyHint annotation: 'image is never stored — processed in memory only' (privacy guarantee), technical details (K-means++, Bradford chromatic adaptation), and a structured list of output fields (archive name, cultural story, RAL standard, WCAG data). No contradiction with 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 a single paragraph of four sentences, efficiently front-loading the main action. Every sentence adds value (purpose, method, output, use cases, data handling). Slight improvement could be made with bullet points for readability, but current structure is good.

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 that an output schema exists (context signal), the description appropriately summarizes output fields. It covers purpose, use cases, behavioral detail, and parameter limitations. Could be slightly more detailed about the matching process or edge cases, but overall complete enough.

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. The description adds algorithm context but does not elaborate on individual parameter values, constraints, or format beyond what the schema already provides. The max n_colours=5 is stated in schema and reinforced in description, adding minimal 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 uses specific verbs ('upload', 'extract', 'match') and clearly identifies the resource ('image'). It distinguishes from sibling tools by mentioning unique features: named archive entries with cultural provenance, Bradford chromatic adaptation, WCAG data. No 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 lists concrete use cases ('product photography, interior photos, artwork, brand assets, and mood boards'), providing clear context. However, it does not explicitly state when not to use this tool or name alternative tools for different needs.

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 reveals that the photo is never stored, uses Claude Vision for analysis, and matches by CIEDE2000 perceptual distance. These details go beyond the readOnlyHint annotation, which already indicates no destructive 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?

The description is two sentences with an example, efficiently conveying purpose, process, and an illustrative case. No extraneous information.

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

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

Given the presence of an output schema (not shown but known), the description adequately covers the input, process, and return elements (seasonal type, depth, undertone, palette). All parameters are addressed.

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?

All 4 parameters have schema descriptions (100% coverage). The description adds extra guidance: 'Face should be clearly visible in natural light' and explains base64 vs URL usage, adding meaningful context 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 clearly states the tool's purpose: upload a portrait photo for personal colour analysis, determining seasonal type, colour depth, undertone, and providing a palette. It distinguishes from sibling tools like image_palette or colour_forensics by focusing on personal analysis.

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 when to use: when you have a portrait photo and want a full personal colour analysis. It provides an example (Deep Winter, True Spring) making context clear. While it doesn't list alternatives, the purpose is sufficiently specific.

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 indicate readOnlyHint=true, and the description confirms this is a read-only computation. Beyond annotations, the description adds behavioral context by explaining the scoring logic and output structure, which helps the agent understand the tool's behavior without contradicting 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 concise and well-structured, front-loading the core purpose. Every sentence provides useful information: definition, thresholds, input format, output fields, and use cases. No wasted 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?

Given the tool's complexity and the presence of an output schema, the description fully covers what the tool does, what input it expects (with field details), and what output it returns. It leaves no significant gaps for agent understanding.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description reinforces the input structure by listing required fields (name, hex, archive, source, notes) and output fields, adding value beyond the schema without being redundant.

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 purpose: scoring alignment between material origin and social consequence of colors. It provides specific score thresholds (1.00, 0.80, 0.50) and distinguishes it from palette generators, making the purpose highly specific and differentiating it from siblings.

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

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

The description lists explicit use cases (investigative reports, forensic briefs, museum content, editorial PDFs) and notes it as a key differentiator for Colour Memory. However, it does not explicitly mention when not to use or alternative tools, but the 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?

Annotations declare readOnlyHint: true, and the description does not contradict this. The description adds behavioral context by detailing the rich output (60/30/10, light behaviour, WCAG, etc.) and notes no destructive side effects. It appropriately supplements the annotation.

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 and front-loaded, starting with the core purpose. It is comprehensive but slightly lengthy; each sentence serves a purpose, though some trimming is possible. Still efficient.

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 (5 parameters, output schema exists, rich output), the description covers the purpose, inputs, outputs, and even directs to the PDF sibling. It is complete for an agent to understand 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?

All 5 parameters have descriptions in the schema (100% coverage), so the description adds limited new information about parameters themselves. It provides usage examples and context but does not significantly enhance schema 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 clearly states the tool generates a complete interior colour specification from a concept or brief, listing specific outputs (60/30/10 assignments, paint matches, light behaviour, etc.) and provides examples. It distinguishes from the PDF sibling tool and implies it is the comprehensive alternative to simpler palette 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 clear context for when to use (input a room concept, type, style) and mentions the PDF sibling for branding. However, it does not explicitly state when not to use this tool or how it compares to other palette tools like palette_specify.

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 readOnlyHint=true. Description adds details beyond this: 'live inventory', 'deterministic', 'no LLM cost'. These behavioral traits are valuable and do not contradict 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?

Two sentences with no wasted words. Front-loaded with the core purpose, followed by return structure and a key behavioral note (deterministic, no cost). Every sentence earns its place.

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

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

For a meta tool with no parameters and an output schema (as indicated by context), the description provides sufficient information about input, output, and usage context. No gaps remain for an agent to safely and effectively use this 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?

Input schema has zero parameters, so schema coverage is 100%. The description adds value by detailing what the output includes (tool count, endpoint list, MCP-exposed tools, usage notes), which is more than just stating 'no parameters required'.

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 'Return' and the resource 'live inventory of all active endpoints and MCP tools'. It distinguishes itself from sibling tools (like accessibility_check, colour_card, etc.) by being a metatool for discovery, not a domain-specific 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 states 'Use this first to discover what the API can do before making calls', providing clear guidance on when to invoke. Mentions 'Deterministic -- no LLM cost', implying it's safe and cheap. No exclusions or alternatives given, but the 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?

Beyond the readOnlyHint annotation, the description discloses that the tool is deterministic and has no LLM cost, which helps the agent understand performance and reliability. No contradictions with 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 concise (3 sentences) and front-loads the purpose, then lists criteria, output, and usage notes. Every sentence adds value, 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?

Given the complexity of a quality audit tool with an output schema, the description adequately covers inputs (palette), criteria checked, and output structure. It could mention that only the palette parameter is required, but the schema already indicates that.

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

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

All parameters have schema descriptions, so description adds little extra meaning. It does mention 'Hex values' for the palette parameter, which aligns with the schema. With 100% schema coverage, 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 clearly states it performs a 'full palette quality audit' on multiple specific criteria (accessibility, cultural risk, tonal balance, colour diversity, archive naming strength) and returns a score, grade, and fix list. This differentiates it from sibling tools like palette_generate or palette_compare.

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 says 'use before shipping any palette', providing a clear when-to-use context. Does not list exclusions or alternatives, but the sibling tools suggest other palette operations, and this tool is positioned as a final quality gate.

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 discloses the types of outputs returned (timelessness scores, etc.), which adds behavioral context beyond the readOnlyHint annotation. It does not contradict the annotation and clearly indicates a read-only operation.

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 efficiently convey the tool's purpose and outputs. No superfluous information; key points 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?

Given the presence of an output schema, the description appropriately lists return components without redundant detail. It covers the main comparison dimensions, though it could briefly mention that the use_case parameter influences the comparison (implied but not explicit).

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 already provides 100% coverage with descriptions for all four parameters. The description adds context about the use_case parameter but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it performs a deep perceptual, cultural, and commercial comparison between two palettes, listing specific outputs like timelessness scores and winner verdict. This distinguishes it from sibling tools like colour_compare (single colors) or palette_audit (comprehensive audit).

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 use by mentioning 'for the stated use case' but does not explicitly guide when to use vs alternatives like palette_verdict or palette_audit. Context from sibling names suggests differentiation, but no direct usage guidance is provided.

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