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 behavioral detail: it never returns a bare empty result for obscure queries, and explains the fallback mechanism through result_path. It also reveals that entity_mode='exact' returns only genus-matched records and discloses how many off-genus records were excluded, which is non-obvious and valuable state information.

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 packed with useful information but every sentence adds value: core purpose, examples, fallback behavior, and entity_mode distinction. It is front-loaded with the primary function and uses examples to cement understanding. There is no fluff or repetition; even the long entity_mode explanation earns its place by clarifying a subtle mode.

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 (8 params, output schema present), the description covers the essential context: what it searches, how it behaves on obscure queries (result_path), how entity_mode changes semantics, and examples of expected matches. The output schema can handle return values, so the description need not repeat them. This is a complete and self-sufficient description.

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

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

The input schema already provides 100% parameter coverage, so the baseline is 3. The description adds meaningful enrichment, especially for entity_mode with a concrete example of 'Rose' vs 'Rose Pink', query examples, and the guarantee about never returning empty results. However, it does not add extra meaning to parameters like limit, year_from, or include_full beyond what the schema already states, so it falls short of a 5.

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+resource: 'Full-text keyword search across all archive colour names and notes.' It lists concrete search facets (name fragment, material, cultural reference, pigment type, historical period) and includes illustrative examples with match counts. It also distinguishes itself from a sibling by stating it 'Complements conceptual embedding search with exact keyword matching.'

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 contrasts this tool with conceptual embedding search, signaling the right context for exact keyword matching. It provides clear guidance on when to use entity_mode='exact' versus plain text search, using the 'Rose' example to illustrate the difference. The behavior of result_path ('direct', 'broadened', 'redirected') tells the user what to expect for different query outcomes.

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?

Annotations already mark the tool as readOnlyHint=true. The description adds transparency by stating 'All computed data -- no LLM cost', clarifying that no external API calls or costs are incurred. It also describes the return payload, providing context beyond annotations.

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

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

The description is a single paragraph that efficiently conveys purpose, inputs, and outputs. It uses bullet-like listing ('Returns: ...') which helps readability. It is not overly verbose but could benefit from slight structural separation (e.g., lines or shorter sentences).

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, 1 required, output schema exists), the description is comprehensive. It covers what the tool does, what inputs it accepts, what outputs it produces, and notes that it is computed (no LLM cost). It also provides usage guidance (pass results to LLM) and compares to alternatives, making it complete.

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

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

The input schema has 100% description coverage for all 5 parameters. The description merely repeats the parameter names (palette, market, medium, etc.) without adding new semantics or constraints. Since schema already documents parameters well, the description adds minimal value here.

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

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

The description clearly states the tool performs a 'complete brand colour intelligence audit in one call' and lists specific outputs (colour roles, WCAG matrix, cultural risk, palette verdict, etc.). It distinguishes from sibling tools by explicitly stating it replaces chaining separate tools like accessibility_matrix and cultural_risk_assessment.

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

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

The description explains when to use this tool (when a comprehensive audit is needed) and notes that it replaces chaining multiple tools. It also suggests passing results to an LLM for narrative. However, it does not explicitly state when not to use it or provide direct alternatives among siblings.

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

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

The description goes beyond the readOnlyHint annotation by detailing the outputs: CIEDE2000 distances, distinctiveness score, ownership verdict, and recommendations. It confirms a read-only operation and provides behavioral expectations 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 sentences, front-loading the key question and followed by a compact list of inputs and outputs. Every sentence is essential, with no redundancy or filler.

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

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

Given the tool's moderate complexity (6 parameters, 1 required) and presence of an output schema, the description covers inputs, key outputs, and usage context. It lacks details on error handling or limitations, but is sufficiently complete for an AI agent to understand its function.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds value by grouping inputs (e.g., brand hex and name, competitor hexes and names) and explaining their roles in the analysis, such as matching competitors in order.

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: checking if a brand can own a color against competitors in a market. It lists specific inputs and outputs, and distinguishes itself from sibling tools like colour_compare and palette_analyse by focusing on brand ownership and competitive analysis.

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

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

The description explicitly says to use the tool before committing to a brand color in a competitive market, and that it replaces manual checks. While it does not mention when not to use it or contrast with specific siblings, the context is clear and actionable.

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 annotations only indicating non-read-only/non-idempotent/non-destructive, the description adds important behavior: it produces a new version under the same brand_ref and marks suppressed claims as superseded. It also discloses that it does not yet involve accounts or reviewer states, providing useful side-effect context.

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

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

Two sentences, front-loaded with the core action and immediately followed by the key behavioral details. No redundancy or filler; every clause adds 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?

The description covers purpose, the relationship to brand_guideline_specify, versioning behavior, optional vs. required actions, and limitations (no approval workflow). With an output schema present, return-value details are not needed, so this is complete for an agent 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 coverage is 100%, so baseline is 3. The description adds value by explicitly tying selected_candidate_id to the chosen candidate, locked_colour_ids to colours locked for future iteration, and suppressed_claim_ids to suppressed/superseded claims, making parameter roles clearer than 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?

The description clearly states the tool records a manual brand colour decision: choosing a brand_guideline_specify candidate, locking colours, and suppressing claims. It also distinguishes itself from the sibling brand_guideline_specify by describing the versioned revision output.

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 references brand_guideline_specify and clarifies that this tool is for decision-making, not a full approval workflow. It implies the right context (after candidates have been generated) and explicitly excludes account/reviewer states, though it does not name 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?

Despite having readOnlyHint=true and destructiveHint=false, the description goes far beyond annotations by disclosing the async generation race: 'This call races generation against a safe ~55s window: a fast generation returns the full result... A slower generation instead returns a compact status: processing... generation keeps running server-side regardless, and is never lost.' It also gives realistic timing estimates and explains that the response's claim_detail_available_via field names the proper follow-up tool. This is rich, non-obvious 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 long but every sentence earns its place: purpose, next-step tools, timing, async behaviour, and fallback instructions are all densely packed and clearly structured. The opening sentence states the key value proposition, and subsequent sentences front-load the most important operational details. No filler or redundancy.

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

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

Given the tool's high complexity (async generation, multiple response variants, follow-up tools, timing constraints), the description is remarkably complete. It covers both possible response forms, how to poll, what to do with the returned refs, and the validity window. The presence of an output schema further reduces the need to enumerate return fields. This description fully equips an agent to invoke the tool and handle its outcomes.

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

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

The description contains no parameter-level explanations, but the input schema itself is detailed and covers most parameter semantics (e.g., palette_input modes, constraints fields, preferences with nested descriptions). With 57% schema coverage, the schema carries the burden reasonably well, and the description focuses on output and flow. The description adds no extra meaning to parameters, 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 highly specific verb and resource: 'Generates the case for a brand's colours, not just the colours themselves: three genuinely different, archive-grounded candidate palettes from a brand brief'. It clearly distinguishes itself from sibling palette tools by emphasizing archive grounding, competitor scoring, accessibility checks, and claim labelling. It also names downstream tools (brand_guideline_claims, brand_guideline_select, brand_guideline_status), making its unique role unmissable.

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 workflow guidance: 'Follow with brand_guideline_select to record which candidate was chosen' and 'Call brand_guideline_status with that brand_job_ref to retrieve the completed result'. It also points to brand_guideline_claims for resolving claim_ids, so the agent knows exactly how to chain calls. However, it lacks an explicit 'when not to use this tool, use palette_specify instead' style exclusion, so it falls just short of full when-to-use/alternative 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?

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?

Annotations indicate readOnlyHint=true, and the description confirms 'Deterministic' and 'No LLM cost,' which adds transparency about side effects and cost. It also lists outputs, providing behavioral context beyond the annotations.

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

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

The description is two sentences, front-loading the main purpose and listing key outputs efficiently. Every sentence adds value, with no wasted words.

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

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

Given the tool's complexity (5 parameters, output schema present), the description is complete. It explains what the tool returns and emphasizes determinism and cost-free operation, leaving no critical 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%, so the parameters are already well-documented in the schema. The description does not add new meaning to the parameters, but it lists the outputs, which indirectly clarifies what the parameters influence. 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 returns a 'complete brand colour system' with specific items like colour roles, light/dark mode maps, typography guidance, usage rules, and design tokens. It uses specific verbs and resources, distinguishing it from sibling tools that focus on individual aspects like accessibility or colour extraction.

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

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

The description says 'Complete brand colour system in one call' and highlights that it's 'Deterministic. No LLM cost.' This implies usage for obtaining a full system reliably. However, it does not explicitly state when not to use it or mention alternatives among the many sibling tools.

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

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

Annotations 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?

Annotations already declare readOnlyHint=true, so the description adds minimal behavioral context. It does not contradict annotations but also does not elaborate on other behavioral aspects.

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?

One sentence with a clear purpose and usage guideline, no redundant words, front-loaded with essential 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 high schema coverage, a single parameter, and presence of output schema, the description fully satisfies the information needs for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, and the description adds an example but does not significantly expand beyond what the schema already defines for the single parameter 'hex'.

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

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

The description clearly states it is a 'compact semantic fingerprint for a single hex colour' and distinguishes it from the sibling tool 'colour_passport', specifying when to use each.

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

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

Explicitly says to use colour_passport for a general colour profile and this tool only when the user explicitly wants the fingerprint format alone, providing clear when-to-use and 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?

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?

Annotations already indicate read-only behavior. The description adds that it matches to 'named archive colours,' implying reliance on an internal colour database, but doesn't clarify how the matching works or any limitations (e.g., number of colours returned). 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, information-dense sentence that efficiently communicates the tool's purpose. No extraneous words.

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

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

Output schema documents the return structure, so the description needn't explain that. However, the description omits details about default behavior (if harmony_types is omitted) and error conditions (e.g., unrecognized hex). For a straightforward read operation, these gaps are minor.

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

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

Both parameters are fully described in the input schema with examples (hex) and a generic description (harmony_types). The tool description adds no further semantic context about parameter values, defaults, or constraints. With 100% schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool returns complementary, triadic, analogous, and split-complementary harmonies matched to named archive colours. It distinguishes the tool from generic colour combination tools, but does not explicitly differentiate from siblings like colour_hooks or colour_story.

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

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

The description provides no usage context, such as when to use this tool versus other colour harmony tools (e.g., colour_combination) or what prerequisites exist. It leaves the agent to infer usage from the tool name and description alone.

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?

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?

Annotations already mark this as read-only (readOnlyHint: true). The description adds that it returns variants, matches, and siblings, but does not disclose potential query behavior (e.g., exact match requirements or handling of unknown colours).

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

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

The description is two short sentences that pack the core functionality and use case without unnecessary words. It is front-loaded with the 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?

Given the tool has one required parameter and an output schema (not shown but present), the description covers what is returned. It lacks details on matching behavior or error cases, but overall it is sufficient for a simple query 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 already fully describes the one parameter 'name' with a clear example. The description restates 'any named archive colour' without adding new semantic information, so it meets the baseline for 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 historical variants, lighter/darker versions, archive matches, and cultural siblings for a named colour. The title and description together make it distinct from sibling tools like colour_compare or colour_harmonies.

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

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

The description says 'Essential for designers exploring around a colour,' which implies a usage scenario. However, it does not explicitly mention when not to use this tool or contrast it with alternatives like colour_compare or palette_generate.

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

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

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 clearly lists all components of the returned design package (palette, narrative, paint matches, accessibility, etc.), adding context beyond the readOnlyHint annotation. It discloses that this is a compound tool that replaces multiple calls, but does not elaborate on error handling or edge cases.

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

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

The description is two paragraphs, front-loaded with the most critical information (compound nature, inputs, outputs). Every sentence serves a purpose, with 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 complexity (7 parameters, 1 required) and the presence of an output schema, the description covers the essential points: what the tool does, when to use it, and what it returns. It does not cover error cases but is sufficient for intended use.

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

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

Schema coverage is 100%, so the schema already documents all parameters adequately. The description mentions 'concept, medium, audience, and constraints' informally but does not add significant new meaning beyond the schema descriptions. 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 explicitly states it is a one-call compound tool that takes a concept and returns a complete design package including specific outputs. It distinguishes itself from sibling tools by naming the tools it replaces (e.g., query_conceptual + palette_from_concept + ...) and clearly identifies its scope as complete, deployable colour direction.

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 guidance: '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.' It names the alternative tools (query_conceptual, palette_from_concept, etc.) to differentiate usage contexts.

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?

The readOnlyHint=true annotation already covers the safety profile, so the description earns credit for adding meaningful context: it discloses that historical claims are templated only from documented fields, room/surface assignment is editorial (not historical fact), orientation constrains candidate selection rather than just narration, and the response is 60-100KB+ and should be referenced via house_ref. This exceeds what annotations alone provide.

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

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

The description is dense but front-loaded with the core purpose. It's on the longer side but every sentence earns its place: purpose, grouping logic, output structure, provenance integrity guarantees, orientation behavior, example, sibling differentiation, and downstream workflow guidance. The only minor deduction is that it is quite long and could arguably be tightened around the example block.

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 9-parameter tool with an output schema, the description is remarkably complete. It explains the grouping methodology, delivers integrity guarantees about historical claims, clarifies editorial vs factual status, discloses orientation's functional role, warns about response size, and provides a complete workflow handoff to palette_pdf. The output schema handles return-value documentation, and the description covers everything else needed 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%, so the schema does heavy lifting on all 9 parameters. The description adds value by clarifying that the 'archive' parameter must be a single archive ('Single archive to draw every room's colours from') and that rooms are cross-grouped, plus explaining that orientation is functional ('constrains candidate selection, not just narration'). It also highlights the house_ref output field which is critical for downstream 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 states a specific verb+resource ('Generate a complete multi-room house colour scheme from a single archive') and explicitly distinguishes itself from interior_specify ('Use interior_specify instead for a single room without cross-room grouping'). It clearly defines the unique value proposition (provenance-grouped, not visual-similarity) and differentiates it from sibling tools.

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

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

The description explicitly states when to use this tool (multi-room, single archive, provenance grouping) and when NOT to use it ('Use interior_specify instead for a single room without cross-room grouping'). It also includes a concrete example with concept, archive, and rooms array, plus a cautionary note about the large response and how to pass house_ref to 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?

Annotations provide readOnlyHint=true, and the description does not contradict it. Beyond annotations, the description discloses the compound nature, the extraction and matching steps, and the final output including a swatch URL. It also notes that style_context restricts archive matching, adding 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 with a clear problem summary: 'one image in, full creative brief out.' It lists capabilities in a single flowing sentence and ends with a practical usage hint, with no 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?

The description covers the task, the alternative, and a key usage parameter. It does not list every possible input combination, but the output schema exists to explain return values. It doesn't explicitly require one of image_url/image_base64 despite 'one image in,' which is a minor completeness gap.

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 each parameter is already documented. The description adds no new parameter-level details, except reinforcing the style_context examples already present in the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Compound endpoint: one image in, full creative brief out,' clearly stating the function and output. It explicitly distinguishes itself from several sibling tools by naming palette_extract, palette_analyse, and agent_brief as separate alternatives.

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

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

The description explicitly recommends using this tool instead of chaining three separate tools, providing clear guidance on when to choose it. It also instructs to pass style_context with concrete examples like 'English cottage garden', 'Victorian', 'MarsColour' for coherent archive matching.

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, and the description adds behavioral context beyond that, such as 'Uses K-means++ extraction plus Bradford chromatic adaptation for accuracy' and the privacy promise. 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 five concise, information-dense sentences with no fluff. Key information is front-loaded: first sentence states the core action and result; subsequent sentences add technical detail, output format, use cases, and privacy.

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 (4 parameters, output schema exists), the description covers the purpose, usage guidelines, algorithm, output details, and privacy. It is fully adequate for an agent to understand 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 baseline is 3. The description adds value by explaining output structure ('Returns up to 5 dominant colours, each with archive name, cultural story, nearest RAL standard, and WCAG accessibility data') and the optional archive restriction, which goes beyond the schema.

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