Colour Memory

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

Annotations already declare readOnlyHint=true, and description adds that it evaluates contrast for a single pair. No contradictions, but does not elaborate on return format 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?

Two sentences, zero waste. The key action is first, followed by usage guidance. Perfectly concise and structured.

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

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

For a simple tool with full schema coverage and output schema present, the description covers the purpose and usage context completely, including sibling differentiation.

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

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

Schema coverage is 100% and description does not add extra meaning beyond implying the two parameters correspond to foreground/background. Meets baseline expectation.

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 'Evaluates contrast for a single foreground/background pair' with specific verb and resource, and distinguishes from sibling tool 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?

Explicitly tells when to avoid this tool and use accessibility_matrix instead for palettes, providing clear guidance on alternatives.

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

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

Annotations declare readOnlyHint=true, which is consistent. The description adds context about the output format (ranked contrast ratios, WCAG grades, recommendations) but does not disclose any behavioral traits beyond what annotations provide. It does not mention potential limitations 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 a single, well-structured sentence that front-loads the core purpose. Every word adds value, 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 presence of an output schema (indicated true) and high schema coverage, the description adequately explains the return value (ranked contrast ratios, WCAG grades, recommendations). It provides sufficient context for an AI agent to understand the tool's function without needing further detail.

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 have descriptions). The description adds meaning beyond the schema by explaining that the return is ranked by contrast ratio with WCAG grades and recommendations, which is not obvious from parameter names 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 verb 'return them ranked by contrast ratio with WCAG grades and specific recommendations', specifying the inputs (background hex, palette) and outputs (ranked list with WCAG grades, recommendations for body text, large text, UI components). 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 usage: given a background and candidate foregrounds, it returns ranked contrasts with recommendations. However, it does not explicitly state when to use this tool over siblings like colour_compare (which compares two colors) or accessibility_check (which checks a whole palette). No exclusions or alternatives 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 provide readOnlyHint=true, and the description adds details about the output (contrast ratios, grades, summary) without contradicting annotations. The description discloses behavioral traits beyond annotations, such as processing all combinations.

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, concise and front-loaded. First sentence states functionality, second adds usage guidance. No wasted words.

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

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

Given the single parameter with full schema coverage, readOnlyHint annotation, and presence of output schema (not shown but indicated), the description is sufficient for an agent to understand when and how to use the tool.

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

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

Schema coverage is 100%, so the schema fully describes the 'palette' parameter. The description adds minimal extra meaning beyond mentioning 'palette array'. 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 'accept' and 'return', specifies the resource (palette array), and details the output (contrast ratio, pass/fail grades, summary). It also distinguishes from sibling 'accessibility_check' by recommending this for multiple checks.

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

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

Explicitly advises to use this tool instead of calling accessibility_check multiple times for a palette, giving clear when-to-use guidance. No explicit when-not-to, but implied by sibling for single checks.

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 valuable behavioral context: 'Deterministic, no LLM cost.' This goes beyond annotations by explaining the tool's reliability and cost profile.

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

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

Two sentences with zero wasted words. The main action is front-loaded, and every sentence adds unique information (what it does, what it returns, its determinism).

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 input, presence of an output schema, and the description listing the types of returned rules, the tool is well-defined. It lacks only a brief note on expected output format, which the output schema likely covers.

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

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

The schema has 100% description coverage for the single parameter (array of hex values). The description adds no additional meaning beyond what the schema already provides, meeting the baseline for full schema coverage.

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

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

The description uses a specific verb 'Convert' and resource 'palette WCAG matrix', listing concrete outputs (safe pairs, AA-only pairs, etc.) that distinguish this tool from siblings 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?

The description implies usage for generating design-system rules from a palette but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria or 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. The description adds the specific Brettel-Vienot-Mollon model, providing additional 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?

A single, concise sentence that effectively communicates the tool's purpose without 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 tool's simplicity, the description is complete. The output schema exists to describe return values, 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 coverage is 100% and the single parameter hex_val is described in the schema. The description does not add extra semantic meaning 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 it returns simulated hex values for three types of color blindness using a specific model. It distinguishes from siblings like accessibility_check and accessibility_font.

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 color blindness simulation but provides no explicit guidance on when to use this tool versus alternatives like accessibility_check.

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

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

The description adds behavioral context beyond the readOnlyHint annotation: it fetches an archive palette, generates outputs, and supports specific models. There is no contradiction with annotations, and it clarifies that locked_palette bypasses queries. It does not mention destructive actions, consistent with readOnlyHint.

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 (under 100 words) and front-loaded with the primary purpose. It efficiently lists output types, supported models, and an example, with no redundant or vague 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 8 parameters and existing output schema, the description covers core functionality: fetching a palette, generating a direction package, and handling special cases like locked_palette. It omits detailed output structure (handled by output schema) and individual parameter defaults, but remains sufficient for an AI to understand when and how to invoke the tool.

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

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

Schema description coverage is 100%, but the description adds meaningful clarity for parameters like locked_palette ('when provided, no archive query is run — these exact colours are used. Prevents palette drift') and style_notes. It also explains the overall flow of fetching and generating, which complements 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: 'Generate a complete colour direction package for another AI agent or image generation model.' It specifies the output components (agent brief, colour tokens, prompts, lighting notes) and supported models, distinguishing it from siblings focused on analysis or 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 provides usage context: 'Use this to make Colour Memory the colour layer for other AI systems' and includes an example. It implicitly guides when to use this tool versus alternatives (e.g., palette_generate for simpler palettes), though not explicitly stating when not to use it.

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

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

Annotations indicate readOnlyHint=true, and the description adds further behavioural details: returns fidelity score, dE2000 distance, match quality per colour, and overall verdict. 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?

Two sentences, no wasted words, front-loaded with purpose. Efficiently conveys all necessary 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 covers all input requirements, workflow context, and return values. The tool is fully specified for its verification role.

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

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

Schema has 100% description coverage. The description adds meaning by explaining that target_palette comes from agent_brief colour_tokens and that image can be supplied as URL or base64, supplementing 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?

Description clearly states the tool verifies colour fidelity of AI-generated images against a target palette from agent_brief. It uses specific verbs ('Verify') and distinguishes from sibling colour tools by focusing on post-generation verification with quantitative metrics.

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 after agent_brief + image generation to close the colour loop, providing clear context. However, it does not mention when not to use or suggest alternatives among the sibling tools.

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

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

Annotations already provide readOnlyHint: true, so the tool is safe. The description adds that the tool generates content (one-liner, short story, tweet) based on archive results, which is transparent about its behavior. 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: two sentences plus an example, no wasted words. It front-loads the core purpose. Slight improvement could be separating the example more clearly, but overall it is efficiently structured.

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

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

Given the tool's complexity (3 parameters, output schema present, annotations), the description covers everything needed: purpose, usage context, example, and output types (one-liner, short story, tweet). The output schema handles return details, so no further explanation is required.

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 explaining the expected_colour parameter as 'the cliche colour to contradict' and the concept parameter as a 'colour concept to subvert', plus an example tying them together. This goes beyond schema definitions.

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

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

The description 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, generate) and resource (archive colour, one-liner), distinguishing it from siblings like palette tools or audits.

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 use cases: 'Use this for public-facing demos, content, and brand storytelling.' It provides an example (love + red) to illustrate usage. However, it does not explicitly state when not to use it or mention alternatives, which keeps it from a perfect score.

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

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

Annotations declare readOnlyHint=true, consistent with description. Description adds rich behavioral context: output structure (coverage matrix, grade, best match, needed source type) that goes beyond safety info.

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 efficient sentences: first defines purpose and output, second gives usage guidance. No wasted words; front-loaded with the most important 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 and the tool's simplicity (2 params, 1 required), the description covers all necessary context: input, output, workflow placement. Complete for an agent to decide when to invoke.

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%, but description adds value by providing example values for 'themes' and explaining optional 'archives'. This aids the agent in understanding usage beyond schema.

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

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

The description clearly states the tool's purpose: given themes, report evidence coverage. It distinguishes itself from siblings by specifying the output (coverage matrix) and use case. The title 'Coverage Gap Report' is descriptive and matches the verb 'report'.

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

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

Explicitly instructs to use this tool BEFORE building archive_report_brief or brief_forensic, and explains why: to prevent ignoring gaps. This provides clear context for when to use versus alternatives.

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

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

The annotation readOnlyHint:true is consistent with the description's mention of 'check' and 'returns', indicating no side effects. The description adds valuable behavioral details beyond the annotation, such as the detection of modern archives (RacingSilks, FootballStrips) and the output fields (anachronism_risk, period_relevance, safe/unsafe phrasing), fully informing the agent of what to expect.

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

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

The description is two sentences long, with the first sentence front-loading the primary purpose and key actions. Every clause adds value: the first outlines detection logic, the second provides a concrete usage example and enumerates return 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 tool has a full input and output schema, the description does not need to explain return values in detail. It concisely covers the essential behavioral context (what it detects, example scenario, output types) without relying on the schema. The example anchors understanding, making it complete for agent decision-making.

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

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

Schema coverage is 100%, so parameters are well-documented structurally. The description adds contextual meaning by mentioning the detection of modern archives and outlining the output fields, which aids understanding of parameter purpose. It stops short of detailing parameter formats or constraints beyond what the schema provides.

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

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

The description starts with a specific verb-resource pair ('Check a list of colour entries for anachronism risk'), clearly indicating the tool's function. It lists distinct detection capabilities (primary source date vs period, modern archive sources) and return values, effectively distinguishing it from sibling tools like archive_cliche or archive_coverage_gap.

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 when-to-use guidance with the concrete example 'prevents a 2011 Jockey Club racing silk registration being presented as Georgian evidence'. It implicitly suggests use for historical document validation, but does not explicitly state when not to use or name specific alternative tools.

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

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

Annotations declare readOnlyHint=true, and the description adds valuable behavioral context: it is an anti-hallucination endpoint that turns absence of evidence into a forensic finding, describing the exact output (nearest archive support, support level, etc.). 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 reasonably concise (3 sentences plus an example) and front-loaded with the core purpose. The example is helpful but slightly lengthens the text. Could be structured with bullet points for clarity.

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

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

Given 4 parameters, 2 required, and an output schema, the description covers the essential context: purpose, example, use cases. It mentions output elements, so completeness is adequate though not exhaustive.

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 meaning by naming the key parameters (hex, proposed_claim) and showing their usage in an example. Minor improvement over 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's function: given a hex value and a proposed claim, it returns whether the archive supports that claim, what is missing, what source is needed, and safe agent wording. It includes an example and distinguishes itself as an anti-hallucination endpoint, unique among siblings.

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

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

The description specifies essential use cases (museum, documentary, editorial, legal, forensic workflows). It implies when to use but does not explicitly state when not to use or suggest alternative tools. Slight gap in excluding non-archive 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?

Despite readOnlyHint annotation, the description adds rich behavioral context beyond annotations: it explains the output includes three categories of provenance, confidence level, citation format, and source-chain detail. There is no contradiction with annotations.

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

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

The description is two concise sentences. The first sentence states purpose and output breakdown. The second provides usage guidance. It is front-loaded and contains no filler.

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

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

Given the complexity (provenance explanation with categories, confidence, citation, and source-chain detail) and presence of an output schema, the description sufficiently covers the tool's function, output characteristics, and appropriate usage contexts.

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 one parameter 'colour_name' already well-described in the schema (including examples). The description does not add further semantic meaning beyond what the schema provides, 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 'Explains' and resource 'provenance of a named archive colour', and distinguishes between documented fact, computational derivation, and cultural interpretation, with confidence and citation format. It differentiates itself from the sibling colour_passport by being a standalone research tool for deep provenance work.

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 provides when to use this tool vs alternatives: 'Use colour_passport for a general profile; call this directly for research workflows needing full source-chain detail.' It also mentions it is suitable for museum, documentary, and editorial 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?

The description adds behavioral context beyond the readOnlyHint annotation by stating it requires two Claude calls and detailing the comprehensive output. This helps the agent understand its operational characteristics.

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 relatively concise given the tool's complexity, with front-loaded purpose. Each sentence adds value, though it could be slightly more streamlined without losing content.

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

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

Given the tool's 7 parameters, full schema coverage, and present output schema, the description adequately covers inputs and outputs. It provides detailed output characteristics, making it complete for selecting and invoking the tool.

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

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

All parameters have schema descriptions, so baseline is 3. The description's narrative list of inputs doesn't add significant new meaning beyond the schema; it mostly rephrases existing information.

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: a comprehensive archive research package for documents, PDFs, or editorial briefs. It distinguishes from siblings by explicitly noting it replaces chaining separate 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 indicates to use this tool first for any document workflow, and positions it as the endpoint for premium archive content. While it doesn't list explicit when-not-to-use scenarios, it provides 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 indicate readOnlyHint=true, and the description reinforces the search nature. It adds behavioral details like default returning 150-char snippets, the include_full flag for report workflows, and year boosting. This goes beyond what annotations provide.

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

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

Two concise sentences: the first defines the tool's core function, the second provides search categories and relationship to sibling. Every word 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 presence of an output schema and comprehensive annotations, the description covers all necessary aspects: purpose, usage context, key behavioral traits, and parameter hints. It is fully sufficient for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% with each parameter having descriptions. The description adds overall context but does not significantly enhance understanding of individual parameters beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it performs full-text keyword search across archive colour names and notes, with specific examples of search topics. It also distinguishes itself from sibling conceptual embedding search, making the purpose unmistakable.

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

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

It explicitly mentions complementing conceptual embedding search with exact keyword matching, providing context for when to use this tool. However, it does not explicitly state when not to use it or list alternative tools, so a score of 4 reflects slight room for improvement.

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

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

Annotations already set readOnlyHint=true. Description adds value by stating 'Deterministic. No LLM cost', which informs about performance and cost characteristics. No contradictions. Additional context about side effects or return size would strengthen, but current info is good.

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 that front-load the purpose. Every word earns its place. 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 high schema coverage, output schema exists, and only one required parameter, the description is mostly complete. It explains what is returned and key traits. However, it could better explain how parameters influence outputs and provide more comparison to sibling tools.

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 all 5 parameters. The description does not add new parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

Description clearly states the tool produces a brand asset pack with specific outputs (CSS variables, Tailwind config, Figma tokens, etc.). It uses strong verbs like 'returns' and 'ships'. However, it does not differentiate from sibling tools like palette_export or brand_system, which may have overlapping functionality.

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?

Implies usage for brand teams needing an export pack, and adds context about being deterministic and having no LLM cost. But there is no explicit guidance on when not to use this tool or alternative tools to consider.

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 behavioral context: 'All computed data -- no LLM cost,' indicating deterministic computation. It also discloses that results can be fed to an LLM for narrative, which is useful. 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, with three sentences that front-load the main function, list parameters, and explain outputs. Every sentence provides value; 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?

The tool has a moderate complexity with 5 parameters and an output schema. The description covers inputs, behavior (no LLM cost), and outputs adequately. It mentions replacing other tools, which adds context. Could optionally include error handling or limitations, but overall complete.

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

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

Schema description coverage is 100%, so the parameters are already documented. The description lists the parameters (palette, market, use_case, medium, brand_category) but adds minimal new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states it performs a 'Complete Brand Colour Intelligence audit' in one call, specifying that it returns multiple computed outputs. It explicitly distinguishes itself from sibling tools like accessibility_matrix, cultural_risk_assessment, and palette_verdict by stating it replaces chaining them 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 provides clear guidance on when to use this tool: for a comprehensive audit in one call instead of chaining multiple separate tools. It also suggests passing results to an LLM for narrative. However, it does not explicitly state scenarios where this tool should not be used or when alternatives are better.

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 the description (a check operation). The description adds behavioral context by detailing the outputs (distances, scores, verdict) and replaces manual checks. No contradictions.

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

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

The description is a single paragraph with a clear flow: question, inputs, outputs, usage. It is reasonably concise (3 sentences) and front-loaded with the core question. 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 (6 params, rich output) and the presence of an output schema, the description covers the main purpose, inputs, outputs, and usage context. It does not cover edge cases or limitations, but overall informs sufficiently.

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 lists the parameters (brand hex, brand name, competitor hexes/names, market, region) but adds no new semantics beyond the schema descriptions, which already include examples.

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 brand colour ownership against competitors in a market, with a specific verb ('check') and resource ('brand colour collision'). It distinguishes from siblings like 'colour_compare' by emphasizing market context and ownership verdict.

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

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

The description explicitly says 'Use before committing to a brand colour in a competitive market' and 'Replaces manual colour distance checks and competitor palette analysis', providing clear when-to-use guidance. It lacks explicit when-not-to-use or direct sibling tool comparisons, 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?

Adds behavioral details beyond annotations: states it runs entirely internally, cannot be blocked by safety filters, and requires two Claude calls. readOnlyHint=true is consistent with a report generation tool that doesn't modify data. No contradiction.

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

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

The description is concise and front-loaded with the tool's purpose, listing outputs in a structured way. While dense with information, it is efficient and 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 (7 parameters with nested objects, extensive outputs), the description covers all aspects: inputs, usage, outputs, and execution behavior. The presence of an output schema handles return value details, so the description 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% with parameter descriptions, but the description adds value by explaining how parameters like 'concept' and 'medium' are used within the report context (e.g., 'concept to search for cliche contradiction'). This 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?

The description clearly states the tool generates a 'complete brand colour intelligence report' in one call, listing specific outputs. It distinguishes from sibling tools like colour_strategy, cliche_breaker, etc. by advising to use this instead of chaining multiple 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 recommends using this tool instead of chaining colour_strategy, cliche_breaker, and other sibling tools. Also notes it runs internally and cannot be blocked by agent safety filters, providing clear context for when to invoke 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?

Discloses determinism and no LLM cost beyond the readOnlyHint annotation. Lists exact outputs, adding transparency about what the tool returns.

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

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

Very concise, front-loaded with key outputs and traits. 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?

With full schema descriptions, an output schema, and annotations, the description is nearly complete. Could add usage guidance but overall sufficient.

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

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

Schema coverage is 100% with good parameter descriptions; the tool description does not add extra semantics for parameters, but no additional value is needed.

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

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

The description clearly states it returns a complete brand colour system including specific components (roles, maps, typography, etc.), distinguishing it from many sibling tools that 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?

Implies it's the comprehensive one-stop tool, but lacks explicit guidance on when to use vs. alternatives. Mentions 'Deterministic. No LLM cost' as a benefit but does not provide 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?

The annotation readOnlyHint=true indicates a safe read operation, and the description adds value by specifying the returned fields (hex, archive, provenance, cultural notes). This provides behavioral context beyond the annotation.

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

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

The description is a single concise sentence with no extraneous information. It is 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?

For a simple lookup tool with an existing output schema, the description is complete. It covers what the tool does and what it returns, without needing 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?

The input schema has 100% coverage with descriptions for both parameters (name and slug). The tool description does not add new meaning beyond the schema for parameters, as it only mentions 'named colour' matching the name 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 clearly states the verb 'look up', the resource 'named colour', and the specific return data (hex, archive, provenance, cultural notes). It distinguishes from sibling tools like colour_compare and colour_mix, which have different purposes.

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

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

The description implies usage when you need colour details by name or slug, but it does not explicitly state when to use this tool over alternatives or provide exclusions. Given the many colour-related siblings, additional guidance would be beneficial.

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

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

Annotations provide readOnlyHint=true, so no destructive behavior is expected. The description adds value by specifying the return content (harmony type, clash warnings, contrast summary, deployment rules) which helps the agent understand the tool's behavioral 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 a single, well-structured sentence that front-loads the action and key details. No unnecessary words, every element earns its place.

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

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

Given the tool's complexity (multiple contexts, return types), the description covers purpose, input constraints, contexts, and output. Output schema exists, so return details are handled. No gaps for an agent to select or 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%, so baseline is 3. The description adds meaning by clarifying the purpose of the output (harmony, warnings, contrast, rules) which indirectly helps parameter understanding, and it explicitly states '2-5 hex values' matching 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 uses a specific verb 'Assess' and resource 'colours as a combination', and lists the contexts (UI, data viz, etc.) which distinguishes it from siblings like colour_harmonies (only harmony) or colour_compare (comparison).

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

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

The description implies when to use (for assessing color combinations across contexts) but does not explicitly state when not to use it or provide alternatives among the many sibling tools. No exclusions 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 mark it as readOnlyHint=true. The description adds value by detailing the behavioral aspects: it returns quantified differences, cultural context, and comparisons of authority, saturation, stability under illuminants, and historical significance. 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, front-loaded with the main purpose, and structured logically. Every sentence adds value without redundancy. It is well-suited for quick understanding.

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 2 parameters, 100% schema coverage, annotations, and an output schema, the description is complete. It explains the tool's purpose, usage, outputs, and exclusions, leaving no significant gaps for an agent to misinterpret.

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%, meaning the input schema already describes the parameters (hex_a and hex_b as hex strings). The description does not add per-parameter details beyond what the schema provides, so it meets the baseline of 3. It does set overall context for the parameters as colors, but that is implicit.

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 begins with 'Deep perceptual and semantic comparison between any two hex values,' clearly specifying the verb (compare) and resource (hex values). It lists the outputs (LRV, chroma, hue angle, etc.) and cultural context, distinguishing itself from sibling tools like colour_harmonies or palette_compare. The title also reinforces 'Perceptual and Cultural' comparison.

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 when choosing between two colours or explaining why one works better than another.' It also clarifies what it is not: 'Not a harmony tool — this is a decision and reasoning tool,' 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?

Annotations provide readOnlyHint: true, so the description does not need to reiterate safety. However, the description adds no additional behavioral context beyond what annotations already convey (e.g., rate limits, destruction). It mentions being a component of colour_passport, but that is more relational than behavioral.

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: first defines the tool, second provides usage guidance and differentiation. Every sentence is essential and there is no filler.

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

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

Given the low complexity (3 optional params, high schema coverage, output schema exists), the description covers what the tool does, when to use it, and its relationship to related tools. 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 description coverage is 100%, so the baseline is 3. The description reinforces that hex is a single value, markets are optional focus, and palette is an optional list, but does not add significant meaning 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 assesses cultural risk for a hex value or palette, listing specific aspects (symbolic weight, regional taboos, etc.). It distinguishes itself from sibling colour_passport by noting it is one component and specifically for palette-level or risk-only queries.

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: use colour_passport for a general profile, call colour_cultural_risk for palette-level risk checks or when only cultural risk is asked. This clearly delineates 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 provide readOnlyHint=true. The description adds context that it produces a fingerprint for a single hex colour and is a component of colour_passport, which is useful 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?

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 it has an output schema, the description need not explain return values. It clearly states the tool's scope and relationship to colour_passport, making it complete for a simple 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% and the description for the hex parameter mirrors the schema's description. No additional meaning is added beyond what the input 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 the tool generates a compact semantic fingerprint for a single hex colour, and distinguishes it from the sibling tool colour_passport by noting it is a component of that more general profile.

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 colour_passport for a general colour profile; use this only when the user explicitly wants the fingerprint format alone.' This tells when to use versus 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 only indicate read-only; the description adds valuable behavioral context: underlying CIEDE2000 matching and Claude material knowledge, and lists specific return elements (verdict, risks, light behaviour, etc.). 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?

Four sentences: purpose, returns, backing, examples. No fluff, front-loaded, well-structured.

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

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

Given annotations, output schema existence, and 5 parameters, the description provides a complete picture: return content, underlying technology, and practical examples. 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?

Input schema has 100% coverage so description need not detail parameters. The description adds meaning through examples and context (e.g., 'ultramarine on lime plaster') but does not elaborate on individual 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 it assesses color safety for physical applications with a specific verb 'Assess' and resource 'hex colour... physical application'. It lists concrete outputs and examples that distinguish it from sibling tools like colour_compare or colour_metrics.

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 physical safety checks, and examples clarify context. However, it does not explicitly state when not to use or name alternatives, which is acceptable given the clear scope.

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

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

The description adds that harmonies are 'matched to named archive colours', providing context beyond the readOnlyHint annotation. However, it does not detail behavior like whether the hex must be an exact match or how it handles missing 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?

Single sentence, 12 words, front-loaded with the action and result. 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?

With an output schema, the return format is covered. But the description omits explanation of what 'named archive colours' are and how matching works. For a tool with moderate complexity, it leaves some questions unanswered.

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

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

Schema coverage is 100% with descriptions for both hex and harmony_types. The description's phrase 'matched to named archive colours' adds slight context but does not significantly enhance parameter 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?

Description clearly states the action (Return) and the resource (colour harmonies), listing four specific harmony types. This distinguishes it from sibling tools like colour_combination or colour_compare, which have different foci.

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

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

No guidance on when to use this tool vs. alternatives. Among many colour-related siblings, there is no mention of context or exclusions, leaving the agent without decision support.

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?

Read-only per annotations; description adds valuable context about tunability by audience/tone and cultural backing, exceeding 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 efficient sentences front-loading purpose and adding context. 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?

Covers purpose, usage, parameters; output schema exists. Missing edge cases like invalid hex, but minor.

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

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

Schema covers 100% of parameters with descriptions; description adds 'tunable' context but no extra semantics beyond 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?

Clearly states it generates a hook sentence, story, tweet, image prompt, and follow-up questions for hex colours, backed by cultural provenance. Distinct from siblings like colour_combination 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?

Explicitly says use to make archive colours shareable, generate content, or power colour chat experiences. Lacks explicit when-not-to-use or alternatives, but sufficient 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 the tool as readOnlyHint=true, which is consistent with the description. The description adds no additional behavioral context (e.g., limitations, auth needs), but there is no contradiction.

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

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

The description is a single, clear sentence with no unnecessary words. It is optimally concise.

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

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

Given the tool's simplicity and the existence of an output schema (per context signals), the description covers the essential behavior. Minor gaps: no mention of edge cases like invalid hex or no matches found. Overall 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?

All three parameters are described in the schema (100% coverage). The tool description adds no additional meaning beyond stating the commercial paint context; the baseline of 3 is appropriate.

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

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

The description clearly states the tool finds the nearest named colour in commercial paint systems, naming specific brands (Farrow and Ball, Little Greene). This distinguishes it from generic colour matching or naming tools among siblings.

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

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

The description implies usage for paint colour matching but does not explicitly state when to use this tool vs. alternatives (e.g., colour_namer, colour_match). No exclusions or context are provided.

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

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

Annotations already declare readOnlyHint=true, indicating safe reading. The description adds value by detailing the exact metrics returned, which is sufficient for this 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, no fluff, front-loaded with key 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 simplicity (single parameter, read-only, with output schema), the description covers purpose, usage, and output completely.

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 parameter description for hex_val. The description does not add additional parameter semantics beyond the schema, earning the baseline score of 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 returns raw perceptual metrics for a single colour, listing specific metrics like LRV, chroma, hue angle, etc. It distinguishes itself from colour_passport, 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 advises using colour_passport for a general profile and this tool only when isolated numeric values are wanted, 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?

Annotations already set readOnlyHint=true, so the tool is read-only. The description adds value by explaining the perceptual model (CIE Lab) and the return of a nearest archive match. It does not introduce any contradictions and provides transparency about the simulation nature.

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

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

The description is extremely concise: two sentences plus an example. Every sentence adds value—defining the model, contrasting with RGB, stating outputs, and giving a concrete use case. 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?

The description explains the simulation model, output (hex value and nearest archive match with cultural context), and provides an example. With an output schema present, the agent can infer the exact return structure. It doesn't cover edge cases or errors, but for a straightforward mixing tool this is sufficient.

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

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

All three parameters are fully described in the input schema (100% coverage). The description adds minimal extra meaning—it repeats hex_a and hex_b as the two colours and ratio's default value. The example provides concrete usage but doesn't deepen semantic understanding beyond schema.

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

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

The description clearly states it simulates subtractive mixing of two colors using CIE Lab space, distinguishing it from screen blending. It provides a concrete example (Prussian Blue and Yellow Ochre) and mentions the output includes a nearest archive match. The title reinforces 'Mix Two 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?

The description explicitly states it uses CIE Lab subtractive mixing (not RGB), giving clear context for when to use this tool. While it doesn't list alternative tools, the purpose is specific enough that an agent can infer usage. Missing explicit exclusion of other colour-related tools, but still 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 provide readOnlyHint. The description adds that names are 'archive-verified' and lists styles, but does not disclose potential limitations, performance, or error behavior beyond what annotations cover.

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 concise sentences: core purpose, style options, and context. Every sentence adds value with no redundancy. Front-loaded with the primary verb 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?

Description covers the main use case and style flexibility but lacks detail on how market, n_names, or product_type affect output. Given the presence of an output schema, it is minimally adequate but could offer more contextual guidance.

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 reiterates style choices but does not add significant extra meaning beyond schema descriptions for parameters like market, n_names, or product_type.

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

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

The description clearly states it generates archive-grounded colour names for hex values with various style options, positioning it within the Shopify naming use case. However, it does not explicitly differentiate from sibling tools like ecommerce_namer, leaving some 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?

No explicit guidance on when to use this tool versus alternatives. The phrase 'core of the Shopify product naming use case' implies context but does not state when not to use it or mention 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 include readOnlyHint: true, indicating no side effects. The description adds detail about the data returned (colour science, archive, hex provenance, etc.) beyond the annotation. It does not contradict annotations and provides useful 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 a single paragraph, front-loaded with 'Canonical single-call colour truth object.' It is dense but contains no unnecessary words. It could be slightly more structured with bullet points, but it is still concise.

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, many output fields), the description provides a comprehensive overview of what is returned, and the output schema exists. It does not need to detail every field.

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

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

Schema description coverage is 100%, and the description does not repeat parameter details. It gives a high-level overview but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool returns a 'Complete Colour Truth Object' for a hex value, enumerating many attributes. It distinguishes itself from sibling tools by stating it '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 says to 'Use this as the foundation call when you need the complete picture' and that 'Every other tool is built on this data,' providing clear context. However, it does not explicitly state when not to use it or suggest simpler 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?

Describes deduplication, batch limit (up to 20), and the comprehensive set of returned fields. Adds value beyond readOnlyHint annotation by specifying behavior like deduplication and limits.

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

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

Single, well-structured paragraph starting with the batch identity, then limit, then return details, then use cases. No redundant or unnecessary 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 presence of output schema and annotations, this description covers all essential aspects: batch capability, limit, dedup, return fields, and use cases. No gaps 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%, but description adds crucial context: the 20-hex limit, automatic deduplication, and clarifies defaults for other parameters. Schema alone doesn't mention these constraints.

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 it is a batch version of colour_passport, accepts up to 20 hex values, and returns a full Colour Passport for each. Distinguishes from sibling colour_passport by explicitly being the batch variant.

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 recommends using for multi-colour workflows, Figma palette analysis, and any case where calling colour_passport separately would be slow. Clearly implies not for single colour use.

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

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

Annotations declare readOnlyHint=true, but the description adds context about using an 'archive-grounded name source with dE2000 distance,' which provides useful behavioral insight 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, front-loads the core purpose, and contains no extraneous information. Every part is valuable.

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

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

Given the presence of an output schema and the tool's moderate complexity, the description sufficiently explains what the tool does and returns. It could mention that the archive parameter is optional and the distance metric, but overall it 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 the description adds minimal value beyond the schema. It mentions 'archive-grounded name source' for the archive parameter but does not significantly enhance 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 returns all developer token formats for a given hex value, listing specific formats. This distinguishes it from sibling tools like colour_namer or colour_hooks, which have different purposes.

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

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

The description implies usage when token formats are needed for a hex, but it does not provide explicit guidance on when to use this tool versus alternatives 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 already declare readOnlyHint=true, and the description reinforces a read operation. It adds context about using archives but does not disclose additional behavioral traits like data sources or rate limits.

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

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

Description is three concise sentences: purpose, use cases, and example. Front-loaded and 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?

Description covers output details well (history, civilizations, archive names) and provides use cases. With an output schema present, this is sufficient. Minor lack of input validation notes, but overall 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 provides 100% coverage for both parameters (hex and n_archives) with descriptions. The tool description adds an example but does not enhance meaning 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 cultural narrative for a given hex value, with a specific example. It distinguishes from sibling color tools by focusing on cultural journey and history.

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 use cases: 'image generation prompts, brand storytelling, and creative briefs.' It does not explicitly mention when not to use or compare to alternatives, but the context is clear.

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

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

Annotations declare readOnlyHint=true, and the description enhances transparency by stating it combines archive grounding and other analyses, implying read operations. No contradictions, and it adds 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 front-loaded with the purpose and is dense but every sentence adds value. Examples at the end provide context. It is well-structured, though slightly lengthy due to comprehensive output enumeration.

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

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

Given the complexity (5 parameters, nested objects, many sibling tools, and existing output schema), the description is highly complete. It enumerates all output fields, explains inputs, and provides usage examples, leaving no major gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing input fields with examples (e.g., 'luxury fragrance brand UK/France/Japan') and clarifying the structure of brand_context and constraints, going 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 identifies the tool as 'the flagship commercial endpoint' that combines multiple analyses (archive grounding, verdict, brand fit, etc.). It distinguishes from siblings by being comprehensive, covering many aspects that sibling tools handle individually.

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 evaluation but does not explicitly say when to use this tool vs alternatives like colour_verdict or colour_hooks. No when-not or exclusion criteria are provided.

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

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

Annotations already declare readOnlyHint=true, and the description confirms a read-only operation by mentioning 'traces' and 'returns.' It adds behavioral context about the output format ('dated sequence of archive entries with primary sources'), which goes beyond the annotation.

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

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

Two concise sentences plus an example, all front-loaded with essential information. Every sentence earns its place 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?

With an output schema present (though not shown), the description does not need to detail return values. It covers the tool's purpose, parameters, and use cases adequately. The example further enriches completeness.

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

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

Schema coverage is 100% with both parameters described. The description adds value by providing a concrete example ('indigo' and its trace) and implying the use of 'concept' as the input, 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?

The description clearly states the tool's function: tracing a colour concept through history with a specific verb ('traces') and resource ('documented appearances across cultures and centuries'). It distinguishes itself from siblings by focusing on chronological historical research, unlike other colour 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 explicitly recommends use cases: 'historical research, provenance chains, and understanding cultural weight.' While it does not state when not to use or list alternatives, the context is clear and sufficient for an AI agent to decide when to invoke this tool.

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

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

The description adds behavioral context beyond the readOnlyHint annotation, detailing what is returned (historical variants, lighter/darker, archive matches, cultural siblings). 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?

Two concise sentences with no wasted words. First sentence explains functionality, second provides usage guidance. 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, the description fully covers the tool's purpose and return value types without needing to specify format. Complete for a 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?

Schema coverage is 100% with a description for the 'name' parameter. The tool description adds context ('For any named archive colour') that reinforces the parameter's purpose.

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

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

The description clearly states the action (return) and resource (historical variants, lighter/darker versions, cultural siblings) for a named archive colour, distinguishing it from sibling tools like colour_harmonies or colour_dna.

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 'Essential for designers exploring around a colour,' providing clear usage context. Does not explicitly mention when not to use alternatives, but the context is strong enough to guide selection.

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

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

Annotations already indicate readOnlyHint=true, but the description adds significant behavioral context: it returns strengths, risks, avoid-if scenarios, and better alternatives. It also mentions underlying methods (CIEDE2000 and Claude cultural intelligence), which goes beyond what annotations provide.

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

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

The description is only 4 sentences, well-organized, and front-loaded with the core purpose and output. Every sentence adds value, and the examples make it highly informative without being verbose.

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, cultural sensitivity), the description covers everything needed: what it returns, how it works (CIEDE2000 and Claude AI), and concrete examples. The presence of an output schema (not shown) further reduces the need for description completeness; the description already suffices.

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 does not need to add much. It reinforces the purpose of use_case with examples, but does not significantly augment the parameter meanings beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool evaluates a hex colour for a specific use case, market, and medium, and returns a decisive verdict. It distinguishes itself from sibling tools by focusing on verdicts (use_with_confidence, etc.) and provides concrete examples, making the purpose very clear.

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

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

The description explains what the tool does and provides examples, but it does not explicitly state when to use this tool versus siblings like colour_cultural_risk or palette_verdict. However, the examples imply its use for evaluative decisions, so it is clear enough for most agents.

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

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

The description reveals that it is a compound tool that combines multiple steps and returns comprehensive results, which is beyond what the readOnlyHint annotation conveys. It adds context about the tool's behavior, but could further detail any side effects or limitations.

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

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

The description is relatively efficient, front-loading the key phrase 'One-call compound tool.' It then lists outputs and usage guidelines without excessive verbosity. However, it could be slightly more concise by trimming minor details.

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 and the description already outlines high-level outputs, it is complete. The tool's complexity is well-addressed: 7 parameters explained in schema, usage context clear, and the description covers what the tool returns.

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 input schema already describes all parameters. The description adds some context by listing what the output contains (e.g., 'historically grounded palette, cultural narrative'), but does not elaborate on individual parameters beyond what the schema provides.

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

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

The description clearly identifies it as a 'One-call compound tool' that takes a concept, medium, audience, and constraints, and returns a complete design package. It explicitly lists the outputs (e.g., palette, narrative, paint matches) and distinguishes it from chaining multiple individual tools, making its purpose unambiguous.

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

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

The description provides explicit guidance: 'Use when an AI agent or user needs a complete, deployable colour direction in a single call. Not for iterative refinement — use individual tools for that.' This clearly tells when to use and when not to, with a direct reference to alternatives.

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

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

The description adds significant behavioral context beyond the readOnlyHint annotation. It explains that the copy is grounded in archive provenance and never generic, and that colour names come from nearest archive match. 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 but includes essential details: purpose, inputs, outputs, examples, and use cases. It is front-loaded with the main purpose. Slightly longer than strictly necessary but well-structured.

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

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

Given the complexity (5 parameters, output schema), the description is complete enough. It explains provenance, use cases, and provides examples. The output schema likely covers return values, so description does not need to repeat 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 coverage is 100%, so baseline is 3. The description adds value by explaining the output structure and the grounded nature of the copy, and provides examples that illustrate parameter usage. It 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?

The description clearly states the tool's purpose: generating complete ecommerce product copy for any colour. It specifies inputs (hex, product type, tone, channel) and outputs (colour name, product title, etc.). This distinguishes it from siblings like 'ecommerce_namer' which likely focuses on naming only.

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: for generating ecommerce product copy, with examples and mention of platforms (Shopify, WooCommerce). However, it does not explicitly say when not to use or mention alternatives, though siblings like 'ecommerce_namer' exist.

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, indicating a non-destructive operation. The description adds significant behavioral details: names are archive-sourced, not invented, with a primary source citation that can be defended. This goes beyond read-only to clarify the sourcing and defensibility behavior.

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

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

The description is concise (single paragraph) and front-loads the core function. It covers all key aspects efficiently. A slight improvement could be using bullet points for the output fields, but it remains clear and well-structured.

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

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

Given the tool's complexity, the description provides complete context: inputs, outputs, use cases, style options, and the unique value of archive-sourced, defensible names. It covers all necessary details for an agent to decide when and how to use it.

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

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

Schema description coverage is 100%, but the description adds meaningful context beyond the schema: limits (up to 40 SKUs), output structure (archive name, source citation, product description, dE2000 distance, etc.), and emphasizes that names are archive-sourced. This enriches 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's purpose: 'Generate archive-grounded colour names for up to 40 product SKUs.' It specifies inputs (hex values, product category, brand name, naming style) and outputs, and distinguishes itself from siblings like colour_namer by focusing on ecommerce product lines with archive-sourced names.

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 mentions use cases ('paint ranges, candle collections, fashion lines, homeware, cosmetics'), providing clear context for when to use. However, it does not explicitly state when not to use or mention alternative tools (e.g., colour_namer for generic needs), which would strengthen 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 does not contradict that. It adds significant behavioral detail: the tool extracts, matches, understands, identifies, suggests, and generates—all read-only operations. It also clarifies the compound nature, which is not obvious from annotations alone.

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

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

The description is dense but well-structured: starts with the compound endpoint overview, lists outputs, provides usage hint, and gives parameter examples. Every sentence serves a purpose with no fluff. It is front-loaded and easy to parse.

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

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

Given the complexity (compound endpoint, 8 parameters, 0 required, output schema present), the description covers the main purpose, usage, and key parameters. It does not discuss edge cases or error handling, but the output schema handles return values. It is largely complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining style_context (coherent archive matching) and product_type (product focus examples). It also provides examples for key parameters, which the schema's descriptions alone do not.

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 identifies this as a compound endpoint that takes one image and produces a full creative brief, listing specific outputs (dominant colours, archive matching, scene understanding, style period, product suggestions, image prompt, swatch URL). It distinguishes from sibling tools by stating 'Use instead of chaining palette_extract + palette_analyse + 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?

Explicitly says to use this tool instead of chaining multiple separate tools, and provides guidance on when to use style_context with examples like 'English cottage garden'. While it doesn't explicitly state when not to use it, the context is clear enough for an agent to decide.

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

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

The description goes beyond the readOnlyHint annotation by disclosing that the image is never stored (processed in memory only) and mentions the algorithms used (K-means++ and Bradford chromatic adaptation). 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 concise and well-structured, front-loading the core functionality and following with supported use cases and transparency details. 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 the presence of an output schema, the description is complete. It covers the process, algorithms, privacy, use cases, and output characteristics without needing to detail return values.

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

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

Schema coverage is 100%, but the description adds value by explaining the output format (archive name, cultural story, RAL standard, WCAG data) and the constraint that n_colours max is 5. This provides context beyond the 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's purpose: upload an image, extract dominant colours, and match to named archive entries with cultural provenance. It distinguishes itself from sibling tools like image_personal or colour_namer by emphasizing the archive matching and cultural story 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 provides explicit use cases (product photography, interior photos, artwork, brand assets, mood boards) and mentions the output includes up to 5 colours with specific data. However, it does not explicitly state when not to use this tool or compare it to alternatives like archive_search or colour_match_paint.

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 complements the readOnlyHint annotation by stating 'The photo is never stored.' It also explains the AI method (Claude Vision) and matching algorithm (CIEDE2000), adding behavioral context beyond the annotation.

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

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

The description is well-structured and front-loaded with the core purpose, but it is slightly lengthy (4 sentences plus an example). It could be more concise without losing clarity.

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

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

Given the tool's complexity (multiple output fields, AI analysis) and the presence of an output schema, the description is complete by explaining the return values, methodology, and privacy aspect. 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 coverage is 100%, so the baseline is 3. The description does not add new parameter semantics beyond what the schema already provides, such as clarifying the difference between image_url and image_base64.

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

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

The description clearly states the tool's purpose: upload a portrait photo for personal colour analysis. It specifies the outputs (seasonal type, depth, undertone, palette) and gives an example, distinguishing it from sibling tools like palette_generate or colour_dna.

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 personal colour analysis from a photo, but does not explicitly state when to use this tool vs alternatives among the sibling tools, nor does it provide 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 indicate readOnlyHint=true, and the description does not contradict this. It adds value by detailing input and output fields (resonance score, material origin, etc.), providing transparency 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 informative but not excessively verbose. Each sentence contributes to clarifying the tool's function, usage, and output. Minor redundancy could be tightened, but overall it is well-structured.

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

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

Given the tool's moderate complexity and presence of an output schema (though not shown), the description adequately covers input, output, and use cases. It provides sufficient context 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%, with both 'entries' and 'score_basis' having descriptions. The description reiterates the input fields but adds no new semantic information beyond the schema, so baseline score of 3 applies.

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 defines the tool's purpose as a semantic metric to align material origin with social consequence, with specific score examples. It explicitly distinguishes from palette generators, differentiating it from sibling tools.

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

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

The description lists specific use cases (investigative reports, forensic briefs, museum content, editorial PDFs), providing clear context. However, it does not explicitly state when not to use the tool 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?

Beyond annotation readOnlyHint=false, description adds ephemeral processing and 5-minute validity. Schema description for image_base64 also notes no size limit, adding transparency for that parameter.

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. Purpose, return value, and usage direction all included efficiently.

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 output schema present, description completes the picture: upload, get id, use downstream. Mentions ephemeral nature and size. Could add auth or error handling but not required.

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). Description adds extra context, e.g., image_base64 note about local uploads and size limit difference, improving semantics.

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

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

Clear verb 'upload' and resource 'image to Colour Memory for ephemeral processing'. Distinguishes from siblings by stating the returned image_id goes to palette_extract or image_brief.

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

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

Explicitly says 'Use for any image over 50 KB' and instructs to pass image_id to downstream tools. Could mention when not to use (e.g., small images), but usage context is clear.

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

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

Annotations have readOnlyHint=true, and description is consistent (generating output, not mutating). It adds behavioral context by detailing rich output components (light behaviour, WCAG, cultural rationale), which is helpful beyond annotations.

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

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

Description is fairly long (3 sentences) with a dense list of output features. Front-loaded with purpose but could be more concise without losing 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 tool's complexity (generating a full specification), the description covers essential aspects like 60/30/10, paint matches, light behaviour, WCAG, and rationale. Output schema likely documents return values, so description is sufficiently 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. Description adds examples and explains the 'avoid' parameter, but does not significantly deepen understanding beyond the 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 a complete interior colour specification from a concept or brief, listing specific outputs like 60/30/10 assignments and paint matches. Examples differentiate from sibling tools like colour_match_paint.

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 examples and mentions an alternative PDF tool, but lacks explicit when-to-use or when-not-to-use guidance relative to many sibling tools. Usage context is implied but not definitive.

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 description adds that the tool is deterministic and has no LLM cost. It describes the return content well. Slightly penalized for not mentioning any potential restrictions (e.g., authentication), but overall good.

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: first states the action and result, second gives usage hint and key attributes. Extremely concise with no wasted words; 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?

Given no parameters and existence of an output schema, the description adequately covers what the tool returns and why to use it. The mention of 'usage notes' is minor. Complete for a simple discovery 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?

No parameters exist, so schema coverage is 100% by default. Description adds context that the inventory is 'live' and dynamic, but doesn't need to explain parameters. Baseline 4 for zero-param tools.

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 'return a live inventory of all active endpoints and MCP tools' with specific details like tool count, endpoint list, and usage notes. It distinguishes itself from sibling tools as a discovery tool to use first before making calls.

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 this first to discover what the API can do before making calls', providing clear when-to-use guidance. No alternatives are needed as this tool is unique for discovering capabilities.

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

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

The description adds behavioral details beyond the readOnlyHint annotation: it explains that the tool returns nearest archive entries with specific fields, performs deduplication, and provides alternatives when confidence is low. This informs the agent about expected behavior and side effects (no destructive actions). 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 concise and well-structured: four sentences, each adding meaningful information. It avoids redundancy, front-loads the core purpose, and provides usage guidance without unnecessary detail.

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

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

Given the tool's complexity (3 parameters, 1 required, full schema coverage, and an output schema), the description is largely complete. It explains when to use, the output format, and key behaviors (deduplication). Minor gaps: it doesn't mention error handling or limits on the number of colours, but these are acceptable given the structured schema.

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

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

With 100% schema description coverage, the baseline is 3. The description adds minimal extra meaning beyond the schema: it mentions 'alternatives when confidence is low' (related to n parameter) and 'restrict to one archive' (for archive parameter). However, it does not elaborate on the colours array structure or weight parameter, leaving the schema to carry the full burden.

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: analyzing a palette of hex colors against the Colour Memory archive. It specifies the verb 'Analyse', the resource 'palette against Colour Memory archive', and details the output (nearest named archive entry with cultural name, source, etc.). This distinguishes it from sibling tools like palette_audit or palette_compare, which have different focuses.

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 extracting colours from a photo or generating a palette.' This tells the agent when to invoke the tool. However, it doesn't explicitly state when not to use it or mention alternative tools for different scenarios, such as if no archive match is needed.

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

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

Description adds 'Deterministic, no LLM cost' and details return values (score, grade, fix list) beyond the readOnlyHint annotation. No contradictions; the deterministic nature aligns with readOnlyHint.

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 concise sentences: function, output, and usage/characteristics. No redundant information; 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 tool has an output schema and 100% parameter coverage, the description adequately covers the audit scope, return format, and usage context. 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 no parameter-specific details beyond the schema, which already fully describes each parameter. No additional semantic value from description.

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

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

Description clearly states it performs a 'full palette quality audit' listing specific evaluation dimensions (accessibility, cultural risk, etc.) and distinguishes it from sibling tools like palette_compare or accessibility_check by emphasizing it's an enterprise quality gate for pre-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?

Explicitly says 'use before shipping any palette', giving clear context. While it doesn't list when not to use or name specific alternatives, the sibling tools provide implicit differentiation, and the purpose is specific enough to avoid 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?

Annotations already declare readOnlyHint=true, so description doesn't need to emphasize safety. It adds value by detailing the comparison scope (perceptual, cultural, commercial) and return types, which are not in annotations.

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

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

Two sentences with no filler; purpose and returns are front-loaded. Every sentence is necessary.

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

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

With output schema present, the description adequately covers input requirements and return types. Given tool complexity, it 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 covers all 4 parameters with descriptions (100% coverage), so baseline is 3. The description mentions 'use case' but does not add new semantics beyond the schema.

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