Colour Memory

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

The description correctly indicates a read-only evaluation, consistent with the readOnlyHint annotation. It does not add extra behavioral details (e.g., error handling), but the annotation already provides the key behavioral trait of no mutation. Sufficient for a simple tool.

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

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

Two sentences, front-loaded with the core action, and immediately provides alternatives. No unnecessary words 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?

For a simple, two-parameter, read-only tool with an output schema, the description is complete. It covers purpose, scope, and alternative tool. No gaps given the tool's simplicity.

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 parameters. The tool description does not add additional parameter semantics beyond what the schema already provides. 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?

Clearly states the tool evaluates contrast for a single foreground/background pair. The description explicitly specifies the scope (single pair) and distinguishes from sibling tool accessibility_matrix for palettes or multiple colours.

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 this tool (single pair) and when to use the alternative accessibility_matrix (palettes or multiple colours). Provides direct guidance on tool selection.

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, so no destructive actions. The description adds behavioral context such as WCAG grading and rankings, which is not in annotations. It does 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?

The description is a single, well-structured sentence that front-loads the input and output. Every word is necessary; no wasted text.

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 rich output schema (not shown, but presence known), the description adequately explains return values: ranked list with WCAG grades and recommendations. No gaps 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 description coverage is 100% for both parameters. The description rephrases the parameters (background hex, candidate foreground colours) without adding new details like format constraints or validation rules. At baseline 3.

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 a background hex and a palette of candidate foreground colors, it returns them ranked by contrast ratio with WCAG grades and recommendations. This distinguishes it from sibling tools like accessibility_check 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 implies the tool is used for selecting accessible font colors but does not explicitly state when to use versus alternatives like accessibility_matrix or palette_analyse. No exclusions or prerequisites 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 already declare readOnlyHint=true, so the safe, non-destructive nature is covered. The description adds that the tool returns contrast ratios and pass/fail grades per combination, which provides some output context. No additional behavioral traits (e.g., auth needs, rate limits) are disclosed, but with annotations present, the burden is lower.

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. The first states the action and output; the second provides usage guidance. No wasted words, and front-loaded with the core function.

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 (one parameter) and existence of an output schema, the description covers the purpose, alternative, and summary of outputs. It lacks mention of error handling or default behavior but is sufficient for a straightforward tool.

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

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

The input schema has 100% coverage with a detailed description of the 'palette' parameter as an array of hex values. The description does not add extra meaning beyond confirming it accepts a palette. Thus, 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 accepts a palette array and returns contrast ratios and pass/fail grades for every foreground/background combination. It explicitly contrasts with sibling 'accessibility_check' by recommending this tool instead of multiple calls, effectively distinguishing its batch 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?

The description provides a clear alternative: 'Use this instead of calling accessibility_check multiple times for a palette.' This guides the agent to choose this tool for full-palette analysis. However, it does not specify scenarios where the matrix might not be needed (e.g., single combo check), slightly reducing completeness.

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 description's 'Deterministic, no LLM cost' adds modest behavioral context. Does not mention prerequisites, side effects, or limitations 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 efficiently convey purpose, outputs, and behavioral traits. No wasted words; 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?

Tool has one simple parameter, clear output (listed), and output schema exists. Description covers input, output, and behavior sufficiently for an agent to understand the tool's scope.

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 with 'Array of hex values'. Description adds meaning by clarifying the palette is a 'WCAG matrix' and that results are actionable rules, enhancing understanding beyond the schema alone.

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 specifies verb 'Convert' and resource 'palette WCAG matrix', lists specific outputs (safe pairs, AA-only pairs, etc.), and clearly distinguishes from sibling tools like accessibility_check or accessibility_matrix.

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?

Implied usage (for generating design-system rules from a WCAG matrix), but no explicit guidance on when to use vs. alternatives like accessibility_check or accessibility_simulate. The note 'deterministic, no LLM cost' hints at efficiency but doesn't replace clear 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 description carries a lower burden. It adds the model name (Brettel-Vienot-Mollon) as context but does not disclose any additional behavioral traits (e.g., input validation, error handling, or output format). Score 3 is appropriate as the description adds some value 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?

A single sentence of 15 words efficiently conveys the purpose, method, and outputs. No wasted words; front-loaded with the key action and result.

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 one simple parameter, a described output (simulated hex values for three types), and an explicit model, the description is fully sufficient for an AI agent to understand the tool's capabilities. The existence of an output schema further reduces the need for additional details.

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

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

Schema coverage is 100% with a clear description for the sole parameter 'hex_val' (including an example). The tool description does not add further meaning, so baseline 3 is correct.

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: returning simulated hex values for three types of colour blindness using a specific model. The verb 'Return' and resource 'simulated hex values' are precise, and the mention of protanopia, deuteranopia, and tritanopia distinguishes it from sibling tools like accessibility_check or colour_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 implies usage for simulating colour blindness effects but does not provide explicit guidance on when to use this tool versus alternatives (e.g., accessibility_check for contrast, or colour_compare for general colour difference). No exclusions or prerequisites are stated.

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

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

Annotations provide readOnlyHint=true, and the description adds extensive behavioral detail: evidence filtering with claim_role='reject', exclusion of weak entries, returning an honest incomplete result with error_code, and applying negative constraints at retrieval time. It also explains locked_palette behavior, going far 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?

Information-dense single paragraph with no filler, including an example and explicit error behavior. Length is justified by the tool's complexity, though a bulleted or segmented structure would improve scannability.

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

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

Covers purpose, outputs, model support, example, evidence filtering, negative constraints, locked_palette mode, and error result. With an output schema present and the description already explaining non-obvious behaviors, it is contextually complete for a 10-parameter tool.

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

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

Schema descriptions already cover all 10 parameters (100% coverage). The narrative adds semantics for locked_palette (exact colours used as-is, no archive query), minimum_claim_strength (evidence-grade floor, not applied to locked_palette), and clarifies how avoid and negation phrases affect retrieval, enriching beyond field 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 opens with 'Generate a complete colour direction package for another AI agent or image generation model' and enumerates exact outputs (prose brief, colour tokens, prompts, lighting notes), distinguishing it from sibling brief tools by specifying the recipient and deliverables.

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

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

States 'Use this to make Colour Memory the colour layer for other AI systems' and clarifies when locked_palette is appropriate vs. archive-grounded retrieval. It doesn't explicitly name alternative tools, but the context is clear enough for an agent to decide when this tool fits.

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 reinforces a read-only operation ('Verify', 'Returns'). It adds behavioral details beyond the annotations, such as the specific return fields (fidelity score, dE2000, match quality, verdict), providing transparency without 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 concise sentences: the first states purpose and inputs, the second lists outputs and usage context. Every sentence adds value with no redundancy or 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 output schema exists (inferred), annotations are complete, and parameters have full schema coverage, the description is sufficient. It explains the workflow context (post-generation, closing the colour loop) that structured fields do not capture, making it complete for an AI agent to 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% (baseline 3), but the description adds semantic value by specifying that the image can be supplied as URL or base64 and that target_palette comes from 'agent_brief colour_tokens', clarifying the relationship between parameters and workflow context.

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 verifies colour fidelity of an AI-generated image against a target palette, using specific verbs ('verify', 'supply', 'returns') and explicitly references the predecessor tool (agent_brief) and sibling context (image generation), distinguishing it from other colour 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 provides explicit usage context: 'Use after agent_brief + image generation to close the colour loop.' It clearly indicates when to use, though it does not mention when not to use or offer 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?

The description discloses that the tool searches an archive and generates creative text (one-liner, short story, tweet). It adds value beyond the readOnlyHint annotation by specifying the outputs and their purpose. No destructive behavior is implied, and the description does 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?

The description is concise at three sentences, each serving a distinct purpose: stating the core functionality, detailing parameters with an example, and listing outputs and use cases. It is front-loaded with the main action and contains no redundant or 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 tool's moderate complexity (3 parameters, 1 required, output schema present), the description sufficiently covers what the tool does and what it returns. It explains the creative output types and use cases. While it could mention potential limitations or required access to the archive, it is largely 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?

Although the input schema already describes all three parameters with 100% coverage, the description adds contextual meaning by providing an example ('love + red returns...') and explaining how each parameter is used in the tool's logic. This helps agents understand the interplay between 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 clearly states the tool's purpose: 'Find the most surprising archive colour for a concept and generate a memorable one-liner subverting the obvious expectation.' It specifies the verb 'find' and 'generate', the resource 'archive colour' and 'one-liner', and distinguishes itself from siblings by focusing on creative contradiction rather than basic color lookup or palette 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 provides explicit when-to-use guidance: 'Supply a concept (e.g. 'love', 'grief', 'luxury', 'power') and optionally the expected colour.' It includes an example and suggests use cases ('public-facing demos, content, and brand storytelling'). However, it does not explicitly state when not to use this tool or mention alternative tools for similar tasks.

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 details the output (coverage matrix with entries, grade, best match, source type needed), adding context beyond the readOnlyHint annotation. 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 two sentences with a clear usage note, front-loading the purpose. 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 output schema, full parameter descriptions, and readOnlyHint annotation, the description fully covers the tool's purpose, usage, and return value. 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 description coverage is 100% (both 'themes' and 'archives' have descriptions). The description provides an example ('e.g. ['opium', 'gin', 'gambling', 'racing']') but adds little beyond the schema. Baseline 3.

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 function: 'Given a list of themes, report which are well-evidenced in the archive and which are under-evidenced or missing.' This provides a specific verb ('report') and resource ('coverage gap'), clearly distinguishing it from siblings like 'archive_report_brief' and '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 gives direct usage guidance: '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: 'Prevents building beautiful reports that quietly ignore half the brief.'

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, which the description does not contradict. The description adds behavioral details: it detects primary source date, checks for modern archives (RacingSilks, FootballStrips), and returns risk levels, scores, and phrasing. 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?

Two sentences with front-loaded purpose and clear details. Every sentence adds value: first states function, second provides example and output fields. 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 complexity (4 params, 1 required) and presence of output schema in the description (listing return fields), the description is complete. It explains inputs, logic, and outputs, adequately covering the tool's functionality.

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 adds value by explaining that it checks primary_source date and archive for modern sources, providing context beyond the schema. However, it does not detail each parameter's format, but schema already covers that.

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 vs period and known modern archives. It distinguishes from sibling tools like archive_cliche by focusing on anachronism, providing a specific verb-resource combination.

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 it is essential for historical documents and gives a concrete example (2011 racing silk vs Georgian). While it does not explicitly say when not to use, the sibling tool list implies alternatives for other archive tasks, providing clear 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 declare readOnlyHint=true which matches the description of a read-only analysis tool. Description explains it returns support levels, needed source types, and safe wording, and emphasizes it avoids hallucination by treating absence as a finding. 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 paragraph front-loads the core action, then provides an example and use cases. Every sentence contributes meaning; no redundancy or fluff.

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

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

Given the 4 parameters and presence of an output schema, the description thoroughly explains the tool's purpose, example usage, and target workflows. It does not need to repeat output schema details.

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

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

Schema has 100% coverage with clear descriptions. The description adds value by giving a concrete example (hex #4A535C + 'cyanosis in a death chamber') and explaining the output structure, which enhances understanding 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?

Clearly states the tool takes a hex value and a proposed claim and returns archive support, missing evidence, needed source type, and safe wording. It explicitly calls itself an 'anti-hallucination endpoint' and distinguishes from sibling tools like archive_search by focusing on evidence gaps.

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?

Mentions essential use cases (museum, documentary, legal, forensic workflows) and implies use when verifying a specific claim against an archive. Does not explicitly state when not to use or name alternative tools, but the context and sibling list provide indirect 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, and the description consistently indicates a non-destructive research tool. Adds useful behavioral context (standalone vs component of colour_passport) but does not override 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?

Three sentences, front-loaded with purpose, then usage context and differentiation. 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 tool's purpose (provenance explanation), presence of an output schema (covering return values), and only one parameter, the description is complete. It covers use cases, alternatives, and scope.

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 single parameter colour_name has 100% schema coverage with a description. The description adds example values ('Love Idleness', 'Woad Vat Blue') which add minimal extra meaning; baseline 3 is appropriate as schema does the heavy lifting.

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 that the tool explains provenance of a named archive colour, distinguishing documentation types (fact, derivation, interpretation) and providing confidence and citation. It differentiates from sibling colour_passport by targeting deep provenance workflows.

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 specifies when to use this tool (deep provenance work in museum, documentary, editorial contexts) vs when to use colour_passport (general profile). Provides clear decision 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 declare readOnlyHint=true, and the description adds extra behavioral context: 'Two Claude calls total' (resource cost), and the output package details (ranked cards, provenance, flags). It also positions the tool as 'the endpoint for building premium archive documents.' 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 dense paragraph that front-loads the core value ('One-call complete archive research package') and every sentence earns its place: inputs, outputs, replacement guidance, call count, and use case. Slightly longer than the ideal two-sentence example but 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?

For a complex tool with 16 parameters and an output schema, the description gives a clear overall picture: what it produces, when to use it, and how it compares to alternatives. It doesn't need to explain return values since an output schema exists. Minor gap: no mention of when NOT to use it (e.g., simple single-colour queries), but the replacement guidance implies 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?

Schema description coverage is 100%, so the baseline is 3. The description lists input categories (title, audience, themes, archives, avoid, colours) but doesn't add syntax or detailed semantics beyond the schema. It offers high-level organization but no extra parameter-specific insight.

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

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

The description states a specific verb+resource+scope: 'One-call complete archive research package for a document, PDF, or editorial brief.' It clearly distinguishes from siblings by explicitly naming the tools it replaces ('Replaces chaining archive_search + get_colour_card + cliche_breaker + agent_brief separately').

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

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

Explicit when-to-use and alternative guidance: 'Use this first for any document workflow' and 'Replaces chaining archive_search + get_colour_card + cliche_breaker + agent_brief separately.' This tells the agent exactly when to choose this tool over chaining simpler 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?

Beyond the readOnlyHint annotation, the description discloses substantial runtime behavior: it never returns a bare empty result, explains the result_path values ('direct', 'broadened', 'redirected'), and reveals that entity_mode='exact' excludes off-genus rows and reports that exclusion count. This goes well beyond what annotations could convey.

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

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

The description is longer than average but every sentence adds either scope clarification, a concrete example, an edge-case guarantee, or a parameter-use caveat. It front-loads the core purpose before diving into behavioral details, though it could be lightly restructured into shorter logical blocks for even easier scanning.

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 9-parameter search tool, the description covers the key decision points: result_path semantics, pagination with offset, entity_mode disambiguation, snippet vs full notes, and archive filtering. Since an output schema exists, the agent has the remaining return-shape details, making this definition complete for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents query, limit, offset, archive, year filters, n_results, entity_mode, and include_full with concrete examples. The description repeats some of this and adds extra illustrative match counts and behavior around paging, but the schema already carries the heavy lifting, 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 opens with a specific verb and resource ('Full-text keyword search across all archive colour names and notes') and enumerates the axes of search ('name fragment, material, cultural reference, pigment type, or historical period'). It also distinguishes itself from conceptual embedding search by stating it performs exact keyword matching, which is relevant given sibling tools like query_conceptual.

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

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

The description clearly says it complements conceptual embedding search, implying when exact keyword matching is preferred, and it explains when to switch entity_mode from 'text' to 'exact' for botanical identity. It does not explicitly name the sibling tools or state when NOT to use archive_search, but the context is strong enough for an agent to choose it appropriately.

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 that it is deterministic with no LLM cost, which reassures about consistency and cost. It does not cover failure modes or edge cases, but given annotation coverage, the additional context is sufficient.

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

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

Two concise sentences, front-loaded with core purpose. Every sentence adds value: first lists outputs, second emphasizes completeness and key traits. 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 description lists all output types, and an output schema exists for further detail. Input is fully described. Some missing context like output format size or behavior with invalid palette values, but overall adequate for a well-annotated 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 100% description coverage, so the schema already documents parameters. The description does not add any parameter-specific meaning beyond what is in the schema, meeting the baseline but not exceeding it.

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 complete brand asset pack with specific outputs (CSS variables, Tailwind config, Figma tokens, citation cards, Markdown guide). It distinguishes from sibling tools like palette_export by emphasizing completeness for shipping.

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 suggests use for final brand delivery ('Everything a brand team needs to ship') and notes deterministic behavior with no LLM cost, implying efficiency. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance compared to siblings like brand_system.

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 that the tool is deterministic and synchronous with no model call, and transparently reveals that verdict generation was previously hidden inside the tool and is now delegated. It also states that audit_status will be PARTIAL or INSUFFICIENT without proper rendered evidence. The readOnlyHint annotation is consistent; 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 long and heavily capitalized, but every section carries decision-relevant information: deterministic compute, hidden model call removal, live-site evidence requirements, and follow-up tool routing. It's dense rather than bloated, though a more structured layout would improve scannability.

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 covers input semantics, return-key behavior (palette_verdict, verdict_copy, audit_evidence.audit_status), downloadable artifacts, and required follow-up calls (palette_verdict, palette_finalize). Given an output schema exists, it doesn't need to detail return structure, but it provides enough for an agent to call and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is met by the schema. The description goes beyond the schema for site_evidence by explaining what counts as a full live-site audit (homepage, about, deep page; rendered evidence from at least two) and that CSS scrapes are insufficient. Other parameters (market, medium, use_case) are merely listed in the description without adding beyond their schema descriptions.

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

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

The description opens with 'Fast, fully deterministic brand colour audit,' naming a specific verb and resource. It differentiates itself from siblings by stating what it replaces (chaining accessibility_matrix + cultural_risk_assessment) and what it does not compute (palette_verdict). This makes the tool distinguishable from palette_audit and related colour 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?

It explicitly says to use palette_verdict as an optional second call for interpretation, and to call palette_finalize when choosing a final palette from the evidence. For live-site audits, it instructs to inspect rendered pages first and pass site_evidence, with a warning that a CSS scrape alone is insufficient. This is explicit when-to-use / when-not-to-use 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?

With readOnlyHint=true, the safety profile is already covered by annotations. The description goes beyond this by disclosing the computational approach (CIEDE2000 distance) and the full output set including verdict and recommendation. It does not mention rate limits or failure modes, but those are not essential for a read-only analytic 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 compact and well-structured: it opens with the core question, follows with a terse input/output summary, and closes with the intended use case and value. Every sentence earns its place, with no repetition 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?

The description gives enough high-level context for an agent to understand when and why to call the tool, and the schema plus output schema cover the remaining details. The only minor gap is that the 'Input:' list could imply all listed fields are required, when the schema only requires brand_hex, and the provenance parameter's subtle behavior is left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter clearly, including complex semantics like competitor_provenance. The description only lists parameter names ('brand hex, brand name, competitor hexes and names, market, region') without adding format details or constraints, so it adds little 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: assessing whether a brand can own a colour against competitors in a market, and lists concrete outputs such as an ownership verdict and distinctiveness score. This distinguishes it from generic colour tools by emphasising ownership/collision, but it does not explicitly name or contrast sibling tools, so it falls short of full differentiation.

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

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

The description gives explicit situational guidance: 'Use before committing to a brand colour in a competitive market' and says it replaces manual colour distance checks and competitor palette analysis. It does not state when not to use it or name alternative tools, so it lacks the full when/when-not/alternatives coverage.

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 explicitly discloses behavioral traits beyond the annotations: it reads a 'frozen brand_ref snapshot', never re-runs generation, and mutates nothing. This directly complements the readOnlyHint/idempotentHint annotations by explaining what 'read-only' means in practice and the immutability of the data source.

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 but delivers a high density of useful information: purpose, return content, read-only behavior, parameter semantics, and reference to a sibling tool. No wasted words; every clause contributes.

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, the description does not need to explain return values. It covers the tool's role, input selection rules, behavioral constraints, and relationship to sibling tools. For a read-only lookup tool with good annotations and schema, this 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?

While the schema already covers all parameter descriptions (100% coverage), the description adds valuable semantic context: it explains that claim_ids are returned inline by sibling tools, that omitting claim_ids returns every claim, and that brand_ref and project_id are mutually exclusive. This meaningfully enriches the bare schema.

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

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

The description starts with 'Resolves claim_id values' and clearly specifies the resource (claim record) and the resolved fields (source, permitted claim text, do_not_say restrictions, claim_role). It also distinguishes itself from sibling tools by referencing brand_guideline_specify and brand_guideline_select, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool: to resolve claim_ids returned inline by the specify/select tools, and how to omit claim_ids to get all claims. It also states the brand_ref/project_id constraint ('Accepts exactly one of brand_ref or project_id, same as brand_guideline_pdf'), offering a clear usage pattern. It does not explicitly mention when to use this tool over alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: it reads a frozen snapshot without re-running specify, never mutates the project, omits sections that have nothing to say, and never presents derived colors as documented-source language. This goes far beyond the annotations and clarifies edge cases.

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

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

Although longer than average, every sentence adds substantive detail about document contents, dynamic page count, candidate selection, or immutability. The description is front-loaded with the core action and avoids fluff, making the length justified.

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 comprehensively covers the tool's behavior, inputs, selection logic, edge cases, and non-mutating nature. Since an output schema exists, not explaining return values is fine. The detail is sufficient for an agent to invoke this correctly without confusion.

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 each parameter has a clear description. The description adds critical semantic value by specifying the mutual exclusivity of brand_ref and project_id, and clarifies the meaning of project_version for the current version. This is a meaningful supplement to 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 renders a client-facing brand colour standard PDF from an existing brand_ref, with a comprehensive list of document contents. It distinguishes itself by explicitly referencing brand_guideline_select and brand_guideline_specify in context, marking it as the PDF rendering step in the brand guideline workflow.

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 on when to use the tool and its exact input constraint ('Accepts exactly one of brand_ref or project_id'). It also explains the candidate-selection behavior (recorded choice vs provisional preview) and explicitly states what it never does (re-runs specify, mutates project), but lacks direct alternatives or when-not-to-use guidance relative to sibling tools like brand_report or palette_pdf.

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

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

With all three annotation hints false, the description carries the behavioral disclosure burden. It adds meaningful context: the operation produces a revised brand_ref with the same reference but a new underlying version, exactly like a versioned house_ref, and it can lock and suppress items. It also explicitly scopes out accounts and reviewer states, which helps the agent understand current limitations.

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

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

The description is information-dense without fluff, and front-loads the core behavior before adding limitation context. Each clause earns its place: what is recorded, what is produced, and what is not yet included.

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 100% schema coverage, the presence of an output schema, and the annotations, the description completes the picture by explaining the versioning behavior, the manual nature, and the exclusion of approval states. An agent has enough context to select and invoke 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 description coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds framing around the decision-recording intent, but does not materially expand on parameter semantics 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 specifies a clear verb ('Records') and resource ('brand_guideline_specify candidate'), and details the three concrete outcomes: chosen candidate, locked colours, and suppressed claims. It also distinguishes the tool's output from the input-producing sibling, brand_guideline_specify, by explaining this records the decision rather than generating candidates.

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

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

The description clearly situates the tool as a manual decision-recording step following brand_guideline_specify, and explicitly excludes the full approval workflow ('No accounts or reviewer states yet'). It does not name a specific alternative tool for approvals or other related workflows, so it stops short of a fully explicit when-to-use versus alternatives statement.

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?

Annotation Contradiction: the description explicitly describes mutating state ('CREATE ONCE, THEN VERSION', 'pass that project_id back... rather than creating a second project', 'a second project is created') while annotations declare readOnlyHint=true. The description does add useful async/timing context, but the direct contradiction with the read-only hint forces a score of 1 per the rubric.

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 long but each segment earns its place: core purpose, downstream routing to claims/select/status, versioning rule, and timing/polling behavior. It is front-loaded with the main purpose and uses structural cues like 'CREATE ONCE, THEN VERSION' and 'TIMING' to make the length navigable. It loses one point for the dense opening sentence.

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 8 parameters, nested objects, an output schema, and asynchronous behavior, the description is nearly complete: it covers the deliverable, follow-up tools, project versioning, both fast and slow response shapes, and polling instructions. Minor omissions such as error conditions and permissions are not critical given the output schema and surrounding context.

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

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

With schema description coverage at 63%, the input schema documents most parameters in detail, including constraints, preferences, palette_input, identity_assets, and continue_project_id. The tool description adds useful continuation semantics for continue_project_id and ties the behavior to the brand brief, but it does not meaningfully explain the remaining 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 opening sentence states a specific verb ('Generates'), resource ('brand colour standard'), and the concrete deliverable: three archive-grounded candidate palettes scored for distinctiveness, accessibility, and claim labels. It differentiates from siblings by explicitly naming brand_guideline_claims, brand_guideline_select, and brand_guideline_status.

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

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

The description gives explicit workflow guidance: follow with brand_guideline_select, resolve claim_ids with brand_guideline_claims, and poll brand_guideline_status if a processing response is returned. It also explains create-once/version semantics via continue_project_id. It stops short of a 5 because it does not provide explicit 'use X instead' exclusions against the many sibling palette/brand tools.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: it's an 'in-process lookup' that never re-runs generation, returns specific status payloads (processing/complete/failed), and handles unknown/expired refs with a structured error 'BRAND_JOB_NOT_FOUND, never a crash or empty success.' This goes beyond annotations and fully discloses side effects and failure modes.

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, but every sentence conveys necessary information: the trigger, the non-mutating nature, all possible return states, and follow-up tool references. It's longer than minimal but appropriately structured for the complexity, with no filler or redundant 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 has an output schema and a single parameter, the description is highly complete: it explains all response variants, the error case, the relationship to brand_guideline_specify, and how to proceed with sibling tools. It leaves no ambiguity about the tool's role or results.

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 parameter brand_job_ref, with the schema already explaining its source. The description adds context by clarifying where the ref comes from and how it's used in the polling flow. This enriches but doesn't fundamentally extend the schema, meriting above baseline.

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 specific purpose: 'Resolves a brand_job_ref returned by brand_guideline_specify when its race-to-complete window elapsed before generation finished.' It uses a specific verb (resolves) and identifies the resource (brand_job_ref). It also distinguishes itself from sibling tools by positioning as a status lookup, not a generation or full-detail tool.

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

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

The description explicitly states when to use this tool (when the race-to-complete window elapsed) and provides alternatives: 'use the returned brand_ref with brand_guideline_select/brand_guideline_pdf/brand_guideline_claims for full detail.' It also clarifies what it doesn't do ('never re-runs generation'), preventing misuse.

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 annotation readOnlyHint=true already indicates a safe read operation, and the description adds valuable context about the tool's aggregate behavior (single complete response, two Claude calls total). It doesn't contradict annotations and provides extra behavioral context not available in the schema.

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

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

The description is a compact paragraph that fronts the purpose, then efficiently lists inputs and outputs, and ends with a usage directive. It is somewhat list-heavy but each element earns its place; 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's complexity (7 params, nested object, multiple outputs) and that an output schema exists, the description fully covers the tool's role, composition, and expected behavior. It explicitly lists all output types and explains how it replaces a multi-tool chain, making the context 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 parameters are well-documented structurally. The description lists key inputs (hex, brand context, markets, medium, product type) but adds little beyond what the schema already specifies. It does not introduce new semantic detail for individual parameters, so baseline 3 is appropriate.

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

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

The description clearly states it produces a 'complete brand colour intelligence report' with specific inputs and outputs. It distinguishes itself from sibling tools by positioning as a composite alternative to chaining multiple tools (colour_strategy, cliche_breaker, etc.), making its purpose unambiguous.

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

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

Explicitly states 'Use this instead of chaining colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief separately', providing a clear alternative and when-to-use. It also notes 'Two Claude calls total' to set expectations on interaction.

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 annotations, the description discloses determinism, zero LLM cost, that the result carries downloadable PNG/PDF/ASE/JSON/CSS artifacts that should be shown to the customer, and a critical anti-pattern warning: 'Never present the archive anchors a colour was derived from as the colours you are recommending.' This is exactly the kind of behavioral gotcha disclosure that prevents misuse, and it is consistent with readOnlyHint being true.

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

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

Four dense sentences with zero filler: purpose, output inventory, determinism/cost, artifact-handling instruction, a behavioral warning, and a routing instruction. Every clause earns its place, and the most decision-relevant facts (breadth, determinism, cost) are front-loaded before the caveats.

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

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

For a tool with five parameters, one required, plus an output schema, the description covers the full surface an agent needs: what is returned, which artifacts to surface to the customer, the evidence-vs-recommendation distinction, and the follow-up call to palette_finalize. The only omission — how parameters influence the output — is minor given 100% schema coverage and the existing output schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters and their defaults. The description adds no parameter-level meaning beyond the schema — it explains outputs and workflow but not how market, medium, use_case, or brand_category shape the result. This is the baseline 3 given full schema coverage.

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

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

The opening phrase 'Complete brand colour system in one call' names a specific verb and deliverable, and the detailed output list (colour roles, light/dark role maps, typography guidance, usage rules, design tokens, citation cards) makes it unmistakable what this tool produces. The 'in one call' framing and the breadth of outputs clearly distinguish it from narrower siblings like palette_generate, colour_strategy, or brand_guideline_pdf.

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 invoke this tool (when the full brand system is wanted 'in one call') and explicitly routes a downstream scenario: 'If you go on to choose a final palette OF YOUR OWN from this evidence, call palette_finalize once with those exact colours.' However, it does not state when-not-to-use it or name simpler alternatives for partial needs, so it stops short of a full 5.

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, indicating a safe read operation. The description adds what data is returned (hex, archive, provenance, cultural notes) but does not mention potential errors (e.g., colour not found), rate limits, or other behavioral traits. It provides some additional context beyond annotations but not enough for a higher score.

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, clear sentence of 12 words. It is front-loaded with the action ('look up') and immediately states the return fields. There is no wasted 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 tool's simplicity (2 optional parameters, output schema exists), the description is fairly complete. It lists the key return fields. However, it does not mention the existence of two input methods (name vs slug) or that slug is more reliable, though this is covered in the schema. Overall, it is adequate for a 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?

The input schema has 100% coverage with detailed descriptions for both parameters (name and slug). The description does not add new parameter semantics beyond what the schema provides. According to the rubric, high schema coverage means a baseline of 3, and the description does not enhance parameter understanding.

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

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

The description clearly states the tool looks up a named colour and returns specific fields (hex, archive, provenance, cultural notes). The verb 'look up' is appropriate for a retrieval tool. However, given many sibling colour tools, it does not explicitly differentiate itself, e.g., from 'colour_story' which might return a narrative or 'colour_forensics' for 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 implies usage for looking up a colour by name, but it does not provide when-not-to-use or alternative tools. The input schema includes a 'slug' field with a note that it is preferred for reliable retrieval, but this guidance is not in the description itself. The description lacks explicit usage 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 mark readOnlyHint=true. The description adds significant behavioral context: it returns harmony type, clash warnings, contrast summary, and deployment rules. No contradictions, and the description enhances understanding of what the tool produces.

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, each earning its place. First sentence states purpose and scope; second lists outputs. No fluff, front-loaded with key 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 2 parameters and an output schema (implied), the description covers return types and context options. Could be slightly more complete by noting error handling or bounds, but generally sufficient for a check 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% (both parameters described). The description adds no new details beyond what the schema provides (e.g., contexts are already listed in 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 uses a specific verb ('Assess') and clearly defines the resource ('2-5 colours as a combination') and context. It lists return types (harmony type, clash warnings, etc.), distinguishing it from siblings like colour_harmonies or colour_cultural_risk that focus on narrower 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 implies usage by listing contexts (UI, data viz, fashion, etc.) and outputs, but does not explicitly state when not to use this tool or compare it to alternatives. Clear context but lacking exclusions.

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

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

Annotations already declare readOnlyHint=true, so the description's burden is lower. The description adds value by detailing what comparisons are made (LRV, chroma, hue, CIEDE2000, cultural context) and what it assesses (authority, saturation, stability). 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?

Every sentence contributes value: first explains what it is and returns, then when to use, then what it is not. Front-loaded with key info, 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?

With an output schema present (context signal), return values are covered. The description makes the tool's purpose and limitations clear. For a simple two-parameter tool with read-only annotations, this is 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%, so baseline is 3. The description only rephrases that it takes two hex values without adding new constraints, examples, or format details beyond what the schema already provides.

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

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

The description clearly states it performs 'deep perceptual and semantic comparison between any two hex values' and distinguishes itself from harmony tools, explicitly calling itself a 'decision and reasoning tool'. Among siblings like colour_combination and colour_harmonies, this sets it apart.

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 when choosing between two colours or explaining why one works better than another. Not a harmony tool.' This provides clear context for when to use and what not to use, though it doesn't name specific alternative tools for harmony tasks.

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 disclose safety. It adds value by explaining the nature of the assessment (symbolic weight, taboos, market flags), but does not elaborate on potential side effects or performance, which is acceptable given the read-only 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, front-loaded with purpose, no wasted words. Every sentence earns its place.

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

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

Given the complexity of cultural risk assessment, the presence of an output schema, annotations, and full parameter coverage, the description is complete. It tells the agent what the tool does, when to use it, and how parameters relate.

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 documents parameters. The description adds meaning by clarifying the relationship between 'hex' (single colour) and 'palette' (list for palette-level checks), which helps the agent decide which to use.

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 cultural risk for a hex value or palette, listing specific aspects (symbolic weight, regional taboos, religious associations, market flags). It distinguishes from the sibling tool 'colour_passport' by explaining this tool is for palette-level risk or when only cultural risk is needed.

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 guides when to use: 'Use colour_passport for a general profile; call this directly for palette-level risk checks or when cultural risk is the only thing being asked about.' This 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?

Beyond the readOnlyHint annotation, the description discloses important behavioral details: the returned result already carries rendered palette downloads (PNG, PDF, ASE, JSON, CSS) and should be shown to the customer. It also warns specifically against presenting archive-derived anchors as recommended colours and mandates palette_finalize for any agent-chosen palette. These are valuable behaviors not inferable from 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?

The description is front-loaded with the core purpose, immediately explains the sibling distinction, and then gives terse but necessary behavioral instructions. Every sentence earns its place: the result-display note, the warning about archive anchors, and the palette_finalize handoff all contribute to correct agent behavior. Nothing is redundant.

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 single-parameter tool with an output schema and read-only annotation, the description is remarkably complete. It covers selection criteria, expected return artifacts, customer-facing display steps, and a critical correctness caveat about recommended colours. No essential guidance appears to be 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?

The input schema fully documents the single required 'hex' parameter with a concrete example, so the schema already carries the semantic load. The description adds only that it fingerprints a single hex colour, which is consistent but does not materially extend parameter understanding. Baseline 3 is appropriate for full schema coverage.

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

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

The description states precisely that this tool produces a compact semantic fingerprint for a single hex colour, and it explicitly distinguishes itself from colour_passport as one component of that broader tool. It further clarifies when to use it, saying to use it only when the user wants the fingerprint format alone. This gives an agent a clear, unambiguous reason to select it over its 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 gives explicit routing guidance: use colour_passport for a general colour profile, and use colour_dna only when the user explicitly requests the fingerprint format alone. It also provides follow-up instruction to call palette_finalize if the agent constructs its own final palette. This fully covers when and when not to use the 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?

The description discloses the tool's read-only nature (consistent with readOnlyHint) and adds context about its methodology (CIEDE2000 archive matching, Claude material knowledge) and output structure. 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, consisting of three well-structured sentences: purpose, output listing, and examples. No redundant information; 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 and existence of an output schema, the description covers purpose, output, and examples adequately. However, it lacks mention of error handling or limitations, which would improve 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%, so the description adds minimal extra meaning beyond the schema's parameter descriptions. The examples implicitly show parameter usage, but no additional semantic guidance is provided.

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 whether a hex colour can be safely specified for a physical application. It lists specific outputs (verdict, risks, actions, light behaviour, etc.) and provides concrete examples, distinguishing it from sibling colour tools like colour_compare 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 implies usage through examples but does not explicitly state when to use this tool over alternatives or provide exclusion criteria. No contrast with sibling tools or prerequisites are mentioned, leaving the agent to infer 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?

With readOnlyHint=true already covering the safety profile, the description adds substantial behavioral context: hay_contrast snaps to Hay's nearest named hue, returns covered:false when the input is near a tertiary region, and never invents a partner. It also discloses that the result already contains downloads and instructs the agent not to present archive anchors as recommendations. This goes far 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 dense and front-loaded with the core purpose, and every clause carries relevant behavioral or usage information. It is longer than a minimal description, but the complexity of the hay_contrast mode and the downstream finalize instruction warrant the length. Some Hay context repeats what the input schema already says, which keeps it from a perfect 5.

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, the output schema presence, and the read-only annotation, the description covers everything an agent needs: what the tool returns, when it fails, what to show the customer, what not to present, and when to route to palette_finalize. No critical operational gap remains.

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 goes further by explaining the behavioral semantics of the hay_contrast parameter value: nearest-hue snapping, tertiary handling, and covered:false. It also clarifies how harmony_types values behave differently from one another. It doesn't add much about the hex parameter beyond the schema, but the hay_contrast detail justifies the score.

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', names the resource ('colour harmonies'), and enumerates the harmony types, so an agent can tell what the tool does. It also meaningfully distinguishes the hay_contrast mode from the fixed-angle types within the tool. However, it does not explicitly differentiate this tool from similar siblings like colour_relationships or palette_generate, so it stops short of 5.

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 when-to-use guidance: it explains the hay_contrast option, says when the tool returns covered:false, and tells the agent to show the rendered palette assets to the customer. It also provides an explicit conditional for a sibling action: if the agent chooses its own final palette, call palette_finalize once with those exact colours.

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 the output is 'backed by the nearest archive colour's cultural provenance,' which provides some behavioral context beyond the annotation. 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 and well-structured, with the main action front-loaded. It lists all output types and tuning parameters efficiently without 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 presence of an output schema, the description sufficiently covers purpose, inputs, and use cases. It provides enough context for an agent to determine when to 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?

Schema coverage is 100%, but the description adds meaning by explaining that audience and tone are tunable parameters, and hex is the input colour. This goes beyond the brief schema descriptions.

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

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

The description clearly states the tool generates multiple types of content (hook sentence, story, tweet, image prompt, follow-up questions) for a hex colour. It distinguishes from sibling tools by focusing on content generation rather than colour analysis or accessibility.

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 use cases: making archive colours shareable, generating content, or powering a colour chat experience. It lacks explicit 'when not to use' guidance, 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 already declare readOnlyHint=true, indicating a safe read operation. The description adds no behavioral details beyond listing included brands, but does 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?

The description is a single concise sentence that front-loads the main purpose with 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?

While output schema exists (so return values need no explanation) and parameters are fully described, the description could be more complete about the matching algorithm or scope of brands, but it is minimally 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% with descriptions for all parameters. The description does not add significant meaning beyond the schema, such as value formats or examples, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Find' and the resource 'nearest named colour in commercial paint systems', and specifically mentions Farrow and Ball and Little Greene, which distinguishes it from siblings like colour_compare or colour_namer.

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 its siblings, such as colour_compare or colour_namer. No context on prerequisites 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?

Annotations include readOnlyHint=true, confirming no destructive side effects. The description adds that the tool returns raw perceptual metrics, aligning with read-only behavior. No contradictions or missing behavioral details 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?

Two sentences that efficiently convey purpose and usage guidance. No superfluous information; front-loaded with the core action and output.

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 (one parameter, read-only, output schema exists). The description fully covers purpose, usage, and constraints, making it complete for an AI agent to 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% (hex_val described with example). The description does not add parameter-specific details beyond the schema, but baseline 3 is appropriate given high schema coverage.

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 raw perceptual metrics' for a single colour, specifying the metrics (LRV, chroma, hue angle, warmth, undertone). It distinguishes from the sibling tool colour_passport by noting this is a component for isolated numeric values, eliminating 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?

Explicit guidance is provided: 'Use colour_passport for a general colour profile; use this only when the user explicitly wants isolated numeric values.' This directly tells the AI agent when to choose this tool over its sibling.

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, consistent with a simulation. The description adds behavioral context: uses CIE Lab subtractive model for perceptual accuracy, and identifies the nearest archive match. 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?

Three sentences efficiently convey purpose, model, and an example. No unnecessary words. Front-loaded with key 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 (context signal shows 'has output schema: true'), the description need not detail return values. It covers input requirements, the model, and provides a concrete example, making the tool fully understandable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds an example with specific hex values, illustrating the type of inputs. However, the ratio parameter is only mentioned by default value in schema; description doesn't elaborate on its effect beyond the example (0.5 as equal parts). Still adds moderate 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 clearly states it simulates perceptual subtractive mixing of two colours in CIE Lab space, distinct from RGB blending. It specifies the output: mixed hex value and nearest archive match. This differentiates it from many colour-related 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?

Explicitly says 'not RGB screen blending' and provides an example mixing Prussian Blue and Yellow Ochre, indicating the tool's purpose for realistic pigment mixing. This helps decide when to use it versus other mixing approaches.

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 description doesn't contradict. Adds behavioral context: names are grounded in real archive sources, enhancing trust. Does not mention any destructive actions or permissions.

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, no fluff. First sentence states purpose, second covers style choices, third reinforces archive grounding and use case. Information is 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?

Adequately covers purpose, style variety, archive grounding, and use case. Output schema exists, so return values are documented elsewhere. Missing are prerequisites or market-specific behavior, but not critical.

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 provides 100% parameter descriptions, so baseline is 3. Description lists style options but doesn't add semantics beyond schema; no new constraints or format 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?

Description clearly states the tool generates archive-verified colour names for any hex value, with specific verb 'Generate' and resource 'colour names'. It mentions naming styles and ties to Shopify product naming, distinguishing it from sibling tools like 'ecommerce_namer'.

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?

Implied usage for colour naming tasks, but no explicit guidance on when to use over alternatives like 'ecommerce_namer'. Lacks when-not-to-use or exclusion criteria.

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

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

Annotations only supply readOnlyHint=true, so the description carries some burden for behavioral disclosure. It adds context that this is a 'single-call' consolidating tool, and details what data is returned, which goes beyond the annotation. It does not mention potential error cases or performance characteristics, but given the read-only hint, the added return-context is valuable and non-contradictory.

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 long but well-structured and front-loaded with the primary purpose ('Canonical single-call colour truth object'). Every sentence carries useful information: return content, usage guidance, alternatives, and concrete examples. The examples add value, though they could be considered slightly verbose for a tool description.

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, rich output schema, many sibling tools), the description is quite complete: it states what data is returned, when to use it, how it relates to alternatives, and provides examples. It does not discuss output schema specifics, but the presence of an output schema reduces that burden. Missing a 'when not to use' or edge-case note, but overall it's sufficiently contextualized.

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 need not explain parameters. It adds minimal parameter meaning beyond schema, only implicitly referencing hex values via examples. The description does not elaborate on n_archive or include_physics semantics, but the schema already covers these, so a 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 states a specific verb and resource: 'Canonical single-call colour truth object. Returns everything known about a hex value'. It clearly enumerates the data categories returned and distinguishes itself from siblings by explicitly naming the tools it replaces ('Replaces chaining colour_dna + archive_provenance + colour_cultural_risk + colour_metrics separately').

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

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

The description gives explicit usage context: 'Use this as the foundation call when you need the complete picture.' It also names the alternative tools it consolidates, which implies when to use those instead (for specific sub-queries). However, it lacks explicit 'when not to use' exclusions or conditional guidance for different scenarios.

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

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

Annotations only provide readOnlyHint=true; the description adds the 20-value limit, automatic deduplication, and the list of return components (colour science, archive anchor, evidence grade, etc.), going well beyond the annotation. This gives the agent important behavioral context for a batch 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 with zero filler. The first sentence front-loads the batch nature and input limit; the second adds use cases. 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 moderate complexity and presence of an output schema, the description covers invocation limits, return contents, and use cases. It's complete enough for an agent to select and call the tool correctly without additional context.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter semantics by noting the 'up to 20 hex values' limit and 'deduplicates hex values automatically', which add constraints not present in the schema for the hexes parameter.

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

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

The description explicitly states it's the 'Batch version of colour_passport' and says it submits up to 20 hex values and returns a full Colour Passport for each, clearly distinguishing it from the singular sibling tool. The verb 'lookup' and 'returns' make the action and resource 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?

Provides explicit usage guidance: 'Use for multi-colour workflows, Figma palette analysis, or any case where calling colour_passport separately for each colour would be slow.' It names the alternative (colour_passport) and implies single-colour lookups should use that instead.

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

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

Beyond the readOnlyHint annotation, the description discloses significant behavior: results are returned in separate blocks by relationship_class, each edge carries an inline 'does_not_mean' caveat, and empty results are true negatives rather than errors. It even gives a concrete example of a caveat (membership in a Wada combination does not assert individual pairing intent). This goes far beyond the annotation and fully explains what the caller should expect.

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

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

The description is dense but every sentence carries information needed for correct invocation: purpose, data scope, result structure, caveat handling, and empty-result semantics. The historical Wada detail adds color but is not strictly necessary; still, it serves to explain why the relationship graph is populated. Overall it is well-structured and front-loaded with the core question.

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 covers the tool's purpose, result format, relationship taxonomy, inline caveats, empty-result meaning, and how to obtain required IDs. Since an output schema exists, the description does not need to enumerate return fields. The one-hop scope is explicit, and the behavioral caveats remove the main risk of misinterpreting results. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with meaningful descriptions. The tool description adds contextual nuance around 'computed' relationships and 'same-name candidates', but it does not introduce new parameter semantics beyond what the schema already states. Per the baseline rule for full schematic coverage, a 3 is appropriate.

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

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

The description opens with a concrete question ('What is this archive record connected to, and why?') and names the exact action and resource: a one-hop lookup over Colour Memory's stored relationship graph. It also actively distinguishes its output types (SOURCE_ASSERTED vs DETERMINISTIC_STRUCTURAL) so a caller cannot confuse this with colour-distance computation. The tool is clearly separated from archive_search and colour_card, which are referenced as sources for record_id.

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 this tool is appropriate: when investigating archival connections via a one-hop lookup, with explicit guidance that an empty result is a true negative, not an error. It also tells the caller where to get valid record_id values (archive_search or colour_card). However, it does not explicitly name sibling alternatives (e.g., why_connected) or state when not to use this tool, so the exclusion guidance is only implied.

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

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

Annotations declare readOnlyHint=true, and the description adds value by explaining the output includes multiple token formats and that names are archive-grounded with dE2000 distance. 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?

Extremely concise: two sentences, front-loaded with the action verb 'Return', and lists specific outputs. 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 presence of an output schema (not visible but indicated as true), the description sufficiently covers purpose, supported formats, and data source. No gaps for a read-only listing tool.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add extra details beyond the schema, achieving baseline adequacy.

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 developer token formats for a hex value, listing specific formats (CSS variable, kebab-case, etc.). It distinguishes itself from siblings like colour_namer by specifying the comprehensive list of tokens.

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 multiple token formats, but does not provide explicit guidance on when not to use it or alternatives among siblings (e.g., colour_namer for a single name).

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 the description adds relevant behavioral context about cultural journey, history, civilisations, and archive names. There is no contradiction, and the description enhances understanding of the output 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 two sentences plus an example, front-loading the core function. Every sentence adds value—purpose, use cases, and a concrete example—with no redundant or vague phrasing.

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 simple tool (2 parameters, output schema present), the description covers the essential: what it does, expected input format, example, and typical use cases. The return format is handled by the output schema, so no further detail is 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%, so baseline is 3. The tool description adds no additional meaning for parameters; the example '#DC143C' illustrates hex input but does not provide new semantic information 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 returns a rich narrative about a colour's cultural journey given a hex value. It specifies the verb 'returns' and the resource 'cultural story', and distinguishes its use for image generation prompts, brand storytelling, and creative briefs, differentiating it from sibling colour 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 provides clear usage context—'Essential for image generation prompts, brand storytelling, and creative briefs'—but does not explicitly state when not to use it or mention alternative tools. It implies appropriate scenarios but lacks exclusion 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 provide readOnlyHint: true, so the description doesn't need to restate safety. It adds 'Single-call' as a behavioral trait, but does not disclose potential limitations, rate limits, or external dependencies. This is adequate but not rich.

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

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

The description is succinct yet information-dense, front-loading the core purpose ('Single-call commercial colour strategy report') and then efficiently listing inputs, outputs, and examples. Every sentence earns its place without 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's complexity (5 parameters, nested objects, output schema exists), the description is complete enough. It explains what the tool does, what inputs it takes, what outputs to expect, and real-world usage examples, fully equipping an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with each parameter documented. The description adds value by summarizing the input structure (hex + brand_context + constraints + markets + medium) and providing examples, helping the agent understand how parameters combine. This goes slightly 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 clearly states the tool's function: 'Single-call commercial colour strategy report' and lists the specific components it combines (archive grounding, verdict, brand fit, etc.). This distinguishes it from sibling tools like colour_verdict or colour_hooks, which focus on individual 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 implies usage for comprehensive strategy needs by listing combined components and providing example scenarios (luxury fragrance, heritage interior). It does not explicitly name alternatives or state when not to use, but the context is clear enough for an agent to make a selection.

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: 'traces documented appearances... Returns a dated sequence' – no destructive actions. Adds context about output format (archive entries with primary sources) beyond the annotation, so a 4 is appropriate.

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, no wasted words. Front-loaded with the core purpose, followed by usage guidance, then a concrete example. Each 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 presence of an output schema (not shown but stated as present), the description need not detail return values. It covers purpose, usage, and behavioral traits thoroughly for a 2-parameter tool. No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the example for the 'concept' parameter and mentions default/max for 'n', but doesn't significantly augment the schema descriptions. Adequate but not exceptional.

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 traces a colour concept through history, returns dated sequence with primary sources. The example 'indigo' concretely illustrates the scope. It distinguishes from sibling tools like colour_story or colour_dna by focusing on chronological historical research.

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 for historical research, provenance chains, and understanding why a colour carries the cultural weight it does.' This gives clear context. Does not specify when not to use or name alternatives, but given the sibling list, it's implied that other tools serve different purposes.

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 result already includes rendered palette downloads and instructs the agent to show them to the customer. It also warns against presenting archive anchors as recommendations and defines the exact next step if the agent chooses its own final palette, which is valuable behavioral context.

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

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

The description is compact and front-loaded: the first sentence states the core function, the second highlights value, and the third provides necessary behavioral guardrails. Every sentence contributes something, though the wording could be tightened slightly without losing meaning.

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 single-parameter read-only tool with an output schema, the description covers the main return contents, how to present them, and the follow-up action when relevant. It does not describe edge cases or limits, but the combination of schema, annotations, and description is sufficient for correct invocation and 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% for the single parameter, so the schema already fully explains 'name'. The description adds little beyond the schema's own 'Named archive colour e.g. Bourton Honey' example; it reinforces that the value should be an archive colour name but does not introduce new semantic meaning.

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

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

The description uses a specific verb ('return') and identifies the exact resource: historical variants, lighter/darker versions, archive matches, and cultural siblings for a named archive colour. It also sets this tool apart from nearby tools by emphasizing the 'exploring around a colour' use case and by explicitly naming palette_finalize as the follow-up for a different action.

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

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

The description clearly frames when the tool is useful ('Essential for designers exploring around a colour') and gives an explicit routing instruction to palette_finalize if the agent forms its own final palette. It does not exhaustively list when not to use it relative to every sibling, but the context and alternative are concrete enough.

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?

Adds context beyond readOnlyHint: describes backing by CIEDE2000 and Claude, and explains return fields (verdict, strengths, risks). 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?

Single well-structured paragraph, front-loaded with purpose. Every sentence adds value; no redundant or excessive text.

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

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

Covers all aspects: purpose, inputs, output, examples, and backing technology. Could mention invalid hex handling, but output schema likely covers that. Adequate for the 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%, but description adds meaning by explaining output verdicts and providing concrete usage examples, which helps agent understand parameter impact.

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?

Clearly states the tool evaluates a hex colour for specific use case, market, and medium. Provides decisive verdicts. Distinct from siblings with specific examples.

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?

Describes what it does and gives examples, but does not explicitly state when to use vs. alternatives like colour_cultural_risk or colour_metrics. No exclusions or alternative tool references.

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 read-only annotation: it is a compound tool that bundles multiple operations, its result includes downloadable artifacts, and it warns against presenting archive anchors as recommended colours. It even instructs the appropriate follow-up call (palette_finalize) when the agent chooses its own final palette.

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

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

The description is longer than a typical one-liner, but every section earns its place: compound identification, output list, usage condition, anti-pattern, and post-call instruction. It is front-loaded with the tool's nature and purpose, though it could be tightened slightly by separating operational instructions from descriptive 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 complexity, the presence of a full output schema, and 100% schema coverage, the description is remarkably complete. It tells the agent when to use it, what it returns, what not to do with the results, and how to follow up. The only minor ambiguity about the 'audience' input is already addressed by the parameter schema.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already thoroughly explains each parameter with examples. The description adds high-level guidance like "audience" and "constraints," but does not clarify that "audience" has no corresponding parameter; meaningful but not essential 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 opens with "One-call compound tool" and specifies the exact inputs (concept, medium, audience, constraints) and outputs (palette, cultural narrative, paint matches, WCAG check, illuminant behaviour, image prompt). It also explicitly distinguishes itself from the individual tools it replaces by naming them, 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?

It says explicitly "Use when an AI agent or user needs a complete, deployable colour direction in a single call" and "Not for iterative refinement — use individual tools for that." This gives both positive and negative conditions and points to alternatives, which is exactly what this dimension asks for.

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, which is consistent with a generation tool. The description adds valuable behavioral context: all copy is grounded in archive provenance, colour names come from nearest archive match, and it lists nine distinct output components. This goes well 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?

Description is four sentences, front-loaded with purpose, and every sentence provides essential information—inputs, outputs, differentiators, 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 has 5 parameters (2 required), a detailed output schema (implied), and annotations, the description fully equips an agent to invoke it correctly. It covers the unique value proposition and practical applications for ecommerce platforms.

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 extra meaning through examples (e.g., 'velvet cushion in Murex Luxury') and explains that the colour name is archive-derived, which is not in the schema. This additional context justifies a score of 4.

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 'Generate complete ecommerce product copy for any colour' and lists specific inputs and outputs. It distinguishes itself from siblings like 'ecommerce_namer' by emphasizing archive-grounded content rather than generic AI copy.

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 indicates usefulness for Shopify, WooCommerce, and editorial product pages, implying when to use. However, it does not explicitly state when not to use or provide alternative tools for different tasks, leaving some guidance implicit.

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 adds that names are archive-sourced, carries citations, and includes confidence scores. It does not mention performance or rate limits, but the disclosure is substantial.

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 informative and well-structured, front-loading the core function. It is slightly lengthy but 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 complexity (5 parameters, output schema exists), the description covers inputs, outputs, use cases, and constraints thoroughly. No gaps identified.

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 documented. The description lists inputs but doesn't add new meaning beyond what the schema provides; style options are mentioned but not elaborated.

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 archive-grounded colour names for product SKUs, with specific inputs and outputs. It distinguishes from siblings by emphasizing archive sourcing and citations, making it unique among tools like colour_namer 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 specifies use cases for paint, candle, fashion, etc. It does not explicitly exclude alternatives but provides clear context. Among siblings, colour_namer exists but is not mentioned as an alternative.

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, which aligns with the extraction (read-only) nature of the tool. The description adds useful behavioral context beyond this: the algorithm used (k-means++), the dual input path requirement (URL vs ID), and the fact that style_context optionally matches against an archive for cultural naming. It doesn't describe rate limits or error behaviour, but for a read-only extraction tool this is adequate.

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 long with zero waste. It front-loads the core purpose and algorithm, covers the critical input logic (URL vs ID, ingest flow), notes functionality (hex weights, cultural matching), and ends with usage positioning. Every sentence contributes meaningful 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 output schema exists, the description doesn't need to explain return values. It adequately covers the dual input modes, the prerequisite ingest_image flow, and the optional analysis feature. The only minor gap is that it doesn't explicitly note grey_card_hex usage context (white balance calibration), but the schema covers that. For a 7-parameter tool with full schema coverage and an output schema, this is well-rounded.

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 all 7 parameters are documented in the schema. The description adds value by explaining the relationship between image_url/image_id (mutually exclusive input options) and clarifies the ingest_image prerequisite flow. However, the description doesn't add much beyond the schema for individual parameters like k, grey_card_hex, or style_context — those are already well-named and documented in the schema itself.

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 extracts dominant colours from a photograph using a named algorithm (k-means++), and specifies the exact inputs (image_url or image_id) and outputs (hex values with proportional weights, optional cultural naming). It also distinguishes itself from siblings by explicitly positioning it before image_brief and referencing ingest_image for upload flow.

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 guidance: requires either public image_url OR image_id; if the user has a raw file without a public URL, call ingest_image first. It also states when to use this tool ('Use this before image_brief when you have an uploaded photograph') and mentions the optional style_context/analyse flow for archive matching. This is excellent when-to-use coverage.

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 the provenance format, names the exact source builds, and explicitly warns that source numbers are not interchangeable and that the response will say so rather than averaging them. This is rich behavioral context that helps the agent anticipate outputs and limitations.

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

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

Although the description is long, every sentence earns its place: main purpose, source inventory, provenance and limitation behavior, example queries, and a critical caveat. It is front-loaded with the purpose and well-structured for a domain-specific query tool.

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

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

Given the rich output schema and annotations, the description covers all necessary selection and invocation context: what question to ask, which sources are involved, what the response will contain, and what it cannot do. No important aspect is missing for an 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?

Input schema covers 100% of parameters, so baseline is 3. The description adds value by enumerating the seven source names and their evidence types, which directly informs the 'sources' parameter and helps shape a good query. It does not comment on mode, max_results, or high_confidence_only, but the schema already describes those.

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

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

The description opens with a specific verb phrase ('Ask a question about how historical colour authorities actually reasoned') and a clear deliverable ('evidence with provenance rather than a summary'). It differentiates itself from the many sibling colour tools by naming seven specific source builds and the exact use cases, such as checking claims attributed to these authors.

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 'Use it for questions like...' examples and explains what the evidence can and cannot support. It does not name alternative tools or give explicit when-not-to-use conditions, but the context is clear enough to guide selection.

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