Colour Memory

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

Annotations include readOnlyHint=true, so the safe read-only nature is already known. The description adds the scope constraint 'single foreground/background pair' but no further behavioral details like return format or edge cases. No contradiction with annotations.

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

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

The description is two sentences with no fluff, front-loading the core function and then giving a concise alternative recommendation. Every sentence earns its place.

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

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

For a simple 2-parameter read-only tool with an output schema, the description covers purpose and usage adequately. The alternative guidance adds context. It lacks mention of output specifics, but the output schema likely covers that, so 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 description coverage is 100% with clear descriptions for both parameters (hex_val and background). The description adds no additional parameter-level meaning beyond what the schema already 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 states 'Evaluates contrast for a single foreground/background pair' with a specific verb and resource, clearly distinguishing it from accessibility_matrix for palettes. It answers what the tool does unambiguously.

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 provides when-to-use guidance: 'For palettes or multiple colours, use accessibility_matrix instead, it replaces multiple accessibility_check calls in one response.' This names the alternative and clarifies scope, leaving no ambiguity.

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

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

The description discloses the behavioral outcome (ranked list with WCAG grades and recommendations), which adds context beyond the readOnlyHint annotation. It does not contradict the annotations, and no side effects or prerequisites are hidden.

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

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

The description is a single sentence of approximately 30 words, clearly front-loaded with the main action and without redundancy. Every phrase contributes to understanding the tool's function.

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

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

For a tool with two required parameters and an output schema, the description adequately covers its inputs, processing (contrast ratio ranking), and output (WCAG grades and recommendations). No further context is necessary for successful invocation.

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

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

Both parameters are documented in the schema with descriptions, achieving 100% coverage. The description adds semantic context by explaining that the background is the base for ranking and the palette contains candidate foreground colors, enriching 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 uses a specific verb 'return' with the resource 'ranked by contrast ratio' and specifies WCAG grades and recommendations, making its function clear. It distinguishes itself from siblings like accessibility_check by focusing on ranking candidate foreground colors for a given background.

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

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

The description implies use when comparing multiple foreground colors against a background, but it does not explicitly state when to use it instead of other accessibility or color tools. No exclusions or alternatives are mentioned, so it earns an 'implied usage' 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?

The readOnlyHint annotation already signals a safe read operation. The description adds meaningful behavioral context by explaining the tool computes all combinations with specific pass/fail grades and summary, and that it is a batch operation to avoid repeated calls. This goes beyond the annotation without contradicting it.

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

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

Two sentences, front-loaded with the core purpose, and the second sentence gives a clear alternative. No extraneous information or repetition of schema details. Highly concise 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?

The tool has an output schema (not shown), so return values are already covered. The description fully explains the tool's role and provides context for when to use it, complementing the complete schema and readOnlyHint annotation. Nothing essential is missing.

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

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

Schema description coverage is 100%, with the palette parameter already described as an array of hex values with example and min/max constraints. The description only echoes 'palette array' without adding further nuance, 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 tool accepts a palette array and returns every foreground/background combination with contrast ratios, WCAG pass/fail grades, and a summary. It uses specific verbs and resource, and explicitly distinguishes itself from accessibility_check by noting it should be used instead of calling that tool multiple times.

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

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

The description explicitly says 'Use this instead of calling accessibility_check multiple times for a palette,' providing clear guidance on when to choose this tool over the named alternative. This is direct and actionable.

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

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

Annotations already declare readOnlyHint=true, and the description adds that the tool is deterministic and has no LLM cost, which are meaningful behavioral traits beyond the annotation. It also enumerates return categories, providing transparency about what the tool produces. No contradictions found.

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 redundancy. The first sentence states the action, the second lists outputs and performance characteristics. Every phrase 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?

With an output schema present, the return values are covered. The description explains what the tool does, its inputs, and deterministic nature. The only gap is not explaining the prerequisite 'WCAG matrix' or when to call it relative to siblings, but this is a minor omission for a single-parameter read-only 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 description needn't repeat parameter details. The description mentions 'palette' in context but adds no syntax or formatting details beyond the schema's 'array of hex values'. Baseline 3 is appropriate since the schema fully documents the only 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 tool converts a WCAG matrix into design-system rules, listing specific outputs (safe pairs, AA-only pairs, etc.). This distinguishes it from sibling tools like accessibility_check or accessibility_matrix by focusing on derived rules rather than validation or raw matrix generation. However, it does not explicitly name a sibling for contrast.

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?

Usage context is implied: 'Deterministic, no LLM cost' suggests it should be used when a rule-based, inexpensive conversion is needed. But there is no explicit 'use this when' or alternatives listed. It assumes the agent knows to call this after obtaining a palette matrix.

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

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

Annotations already declare readOnlyHint=true, confirming a safe read operation. The description adds value by naming the specific transformation model (Brettel-Vienot-Mollon) and the three output variants, providing 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?

Single sentence, front-loaded with the action and output, with no wasted 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?

For a single-parameter tool with an output schema, the description sufficiently states the purpose and model. No further behavioral details are needed for this simple pure function.

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

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

Schema coverage is 100%, with hex_val fully described. The description doesn't add extra parameter semantics; it only mentions 'hex values' generically, so it meets the baseline without further enrichment.

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

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

The description uses a specific verb ('Return') and resource ('simulated hex values'), listing the three colour blindness types. This clearly distinguishes it from sibling tools like accessibility_check, which focus on checking rather than simulating.

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 colour blindness simulation via the listed conditions (protanopia, deuteranopia, tritanopia). However, it does not explicitly mention when not to use it or name alternative tools, though the context is clear from the sibling set.

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

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

ReadOnlyHint already says no mutation; the description adds substantial behavioral detail: evidence filtering rules, honest incomplete results (ok:false, INSUFFICIENT_EVIDENCE_ELIGIBLE_PALETTE), negative constraints applied at retrieval time, and locked_palette skipping all filtering. This far exceeds the annotation baseline.

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

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

The description is long and organized in paragraphs, but every section adds necessary behavior context for a 10-param tool. It is front-loaded with a clear summary sentence, then details filters, error handling, and special modes. No filler, though the length keeps it from a 5.

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

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

Given the output schema exists, the description doesn't need to list return fields, but it still enumerates the package components (brief, tokens, prompt, negative prompt, lighting notes), covers error codes and edge cases, and gives supported models. This is complete for the tool's complexity.

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

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

All 10 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds meaning beyond schema by explaining how avoid and negation phrases affect retrieval, what minimum_claim_strength means in practice (reject entries excluded regardless), and that locked_palette uses colours as-is. It doesn't cover every parameter but the critical ones get enriched, so 4.

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

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

The first sentence states a specific verb+resource: 'Generate a complete colour direction package for another AI agent or image generation model.' It explicitly names the deliverable and distinguishes from sibling palette/image tools by the 'for another AI' framing. Example task/concept/model anchors real usage.

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

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

The description says 'Use this to make Colour Memory the colour layer for other AI systems,' providing clear when-to-use context. It also contrasts locked_palette vs archive-grounded retrieval paths, but it does not explicitly name alternatives among siblings or give when-not-to-use exclusions, so a 4.

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 detail by specifying the return format: fidelity score 0-100, dE2000 distances, match quality categories, and a verdict. This goes beyond the annotation to clarify what the tool computes and reports.

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 focused sentences cover purpose, inputs, outputs, and usage timing with no filler. The structure is front-loaded with the core action, making it easy to scan.

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

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

Combined with a rich output schema and readOnly annotation, the description covers the tool's role in the workflow, input options, and output semantics. It leaves little ambiguity about 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 has 100% coverage so baseline is 3. The description adds nuance by indicating that the image can be supplied via URL or base64 (implying either/or), and ties target_palette to agent_brief colour_tokens, which is not explicit in the schema. This extra guidance supports correct invocation.

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 a specific action ('Verify') and a specific resource (AI-generated image colour fidelity against agent_brief). It distinguishes from siblings by referencing agent_brief colour_tokens and dE2000 metrics, making it unique among colour/palette tools.

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

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

Explicitly instructs to use 'after agent_brief + image generation to close the colour loop', providing a clear usage context. It also describes what inputs to supply. However, it does not mention when not to use or name alternative tools, so it falls short of full exclusionary guidance.

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

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

The description discloses the behavioural process: 'The archive finds the contradiction and Claude writes the one-liner, short story, and tweet,' and shows an example. This adds value beyond the readOnlyHint annotation, which only indicates no side effects. 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 front-loaded with the main purpose, followed by input instructions, an illustrative example, and a use-case sentence. It is compact and every sentence contributes meaningful information without 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?

The description covers the tool's purpose, input details, example output, and target use cases. Since an output schema exists, the return format is already documented. It does not mention n_results explicitly, but the schema covers that, so no significant 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 descriptions already cover all three parameters (100% coverage), so baseline is 3. The description adds semantics by providing concrete examples (e.g., 'love', 'red') and illustrating how they interact (love + red returns Shakespeare's dark green), which helps the agent choose appropriate values.

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: find the most surprising archive colour for a concept and generate a one-liner, short story, and tweet subverting expectations. This specific verb+resource combination and the mention of creative outputs distinguish it from sibling tools like archive_search 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?

It explicitly says 'Use this for public-facing demos, content, and brand storytelling,' providing a clear when-to-use context. It does not explicitly state when not to use it or name alternatives, but the use case is sufficient.

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

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

Annotations declare readOnlyHint=true, and the description is consistent with a read-only reporting tool. The description adds context about the coverage matrix output and the strategic benefit, but does not disclose additional behavioral traits such as limitations, data sources, or performance characteristics. With annotations covering the safety profile, this is a baseline score.

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

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

The description is four sentences, front-loading the core purpose before output details and usage guidance. Each sentence contributes useful information, though the final sentence about 'beautiful reports' is slightly promotional and could be trimmed without losing essential guidance.

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

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

For a read-only tool with full schema documentation and an output schema, the description provides sufficient context to select and invoke the tool correctly. It explains when to use it, what it returns, and why it matters, making it self-sufficient for an agent to understand its 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 description coverage is 100%, with both parameters (themes and archives) already well-documented. The description only restates that it takes a list of themes, adding no new semantic detail beyond the schema. Baseline 3 applies because the schema carries the parameter documentation 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 reports which themes are well-evidenced versus under-evidenced or missing, with a specific output format. It distinguishes itself from archive_report_brief and brief_forensic by positioning as a pre-flight check, but does not explicitly differentiate from the similarly named sibling archive_evidence_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 explicitly instructs to use this tool BEFORE building an archive_report_brief or brief_forensic, providing strong contextual timing. It also explains the rationale (preventing reports that ignore evidence gaps). However, it does not mention when not to use it or name alternative tools like archive_evidence_gap.

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

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

Annotations already declare readOnlyHint=true, so the bar is lower. The description adds useful behavioral context: it detects whether primary_source date falls outside the period, flags known modern archives (RacingSilks, FootballStrips), and returns specific fields (risk level, period_relevance, safe/unsafe phrasing). This goes beyond the annotation without contradiction.

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

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

The description is composed of four purposeful sentences covering definition, detection logic, a use-case example, and output fields. No wasted words, though it is a bit longer than strictly 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 an output schema and read-only annotation present, the description adequately explains the tool's role and return values. It could be more explicit about expecting entries to contain archive and primary_source fields, but that is inferable from the schema.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds semantic value by explaining that 'archive' values like 'RacingSilks' are known modern sources and linking 'primary_source' to date checking, giving meaning beyond the schema's bare 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 states a specific verb ('check') and resource ('colour entries') and defines the exact risk detection criteria (source date vs period, known modern archives). It clearly distinguishes from sibling tools like archive_coverage_gap or colour_cultural_risk by focusing on anachronism, with a concrete example.

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

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

The description provides clear usage context: 'Essential for historical documents' and a tangible example of a 2011 racing silk being misdated as Georgian. However, it does not explicitly mention alternatives or when NOT to use the tool, which would elevate it to a 5.

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

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

Annotations only declare readOnlyHint=true, and the description adds meaningful behavioral context: it turns absence of evidence into a forensic finding, returns support levels (supported/partial/unsupported), and provides safe agent wording. This goes beyond the annotation without contradicting it.

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

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

The description is front-loaded with the core behavior and is about five sentences long. The example is helpful, though the output list is partly repeated between the first sentence and the example, making it slightly less concise than it could be.

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

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

The description covers the tool's purpose, output, and target workflows. Given that an output schema exists, it does not need to enumerate return fields in detail. It lacks explicit sibling differentiation and limitations, but overall provides enough context for an agent to select and 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 description coverage is 100%, so the baseline is 3. The description adds a concrete example ('#4A535C' + 'cyanosis in a death chamber') and explains the intent of proposed_claim, but it does not add new parameter-level syntax or constraints beyond the schema.

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

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

The description opens with a specific verb ('return') and precisely names both inputs ('hex value' and 'proposed claim') and outputs (support decision, missing evidence, source type, safe wording). It also positions the tool as Colour Memory's anti-hallucination endpoint, clearly distinguishing it from siblings like archive_search 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 states the tool is 'essential for museum, documentary, editorial, legal, and forensic workflows' and gives an example scenario. It implies use when an agent has a proposed claim about a colour and needs evidence validation, but it does not explicitly name alternatives or state 'when not to use'.

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

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

Annotations include readOnlyHint: true, and the description aligns by using 'explains' without implying mutation. The description adds meaningful behavioral context by enumerating what the provenance categories are and that confidence and citation format are returned. It goes beyond the annotation but doesn't discuss potential delays or limitations, so a 4 is appropriate.

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

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

The description is two sentences, front-loaded with the core purpose, then immediately provides usage guidance. Every phrase earns its place with no fluff or repetition.

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 simple input (one string), the presence of an output schema, and readOnly annotation, the description is sufficient. It explains what the tool returns at a conceptual level, when to use it, and how it differs from the closest sibling, making it complete for the complexity involved.

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

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

The single parameter 'colour_name' is fully described in the schema with examples, and the description repeats the notion of a 'named archive colour' without adding additional syntax or format details. Since schema coverage is 100%, the description adds marginal value here.

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

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

The description clearly states the tool explains provenance of an archive colour and specifies the types of provenance (documented fact vs computational derivation vs cultural interpretation) along with confidence and citation format. It also distinguishes this from the sibling tool colour_passport by positioning it as a standalone deep-research tool.

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

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

The description explicitly tells when to use this tool versus the alternative: 'Use colour_passport for a general profile; call this directly for research workflows needing full source-chain detail.' It also names target use cases (museum, documentary, editorial), providing clear context.

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

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

The description reveals that it makes 'Two Claude calls total', which is a behavioral trait beyond the readOnlyHint annotation. It also describes the composite nature, replacing multiple tools, and the full output list. This adds meaningful context without contradicting annotations.

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

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

The description is long but well-structured with an 'Input:' and 'Output:' list, front-loading the core purpose. Each section earns its place; the alternative naming and usage instruction are not filler. It is appropriately dense for a complex 16-parameter tool.

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

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

Given the complexity (16 params) and presence of an output schema, the description does not need to explain return values. It covers purpose, inputs, outputs, alternatives, and usage in enough detail. It could mention edge cases or error behavior, but the output schema likely handles that, so 4 is fair.

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

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

The input schema already has 100% coverage with descriptions for all 16 parameters. The description's input list ('title, audience, themes, archives to draw from, things to avoid, number of colours') just summarizes the schema and adds no new per-parameter semantics. Therefore 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 this is a 'one-call complete archive research package' for documents/PDFs/briefs, explicitly distinguishing it from chaining individual tools like archive_search and get_colour_card. It names the tool as the endpoint for document workflows, providing specific verb + resource + scope.

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

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

It explicitly says 'Use this first for any document workflow' and identifies alternatives by naming the tools it replaces ('Replaces chaining archive_search + get_colour_card + cliche_breaker + agent_brief separately'). However, it doesn't explicitly state when to avoid it in favor of those individual tools.

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

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

Beyond the readOnlyHint annotation, the description discloses non-obvious behaviors: never returns a bare empty result, may fall back to semantic search, and how entity_mode changes results (e.g., 'Rose' excludes Sweet Peas named 'Rose Pink'). This adds rich context that annotations alone cannot provide.

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

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

The description is dense and information-rich, with every sentence serving a purpose. It could benefit from paragraph breaks for readability, but it is not verbose or redundant; it wisely front-loads the core purpose and then layers examples and edge-case behavior.

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 search tool with 8 parameters and an output schema, the description covers all essential context: matching behavior, fallback logic, entity mode, result_path semantics, and parameter interplay. It is complete enough for an agent to use the tool correctly without additional lookups.

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?

Even with 100% schema coverage, the description adds meaning: it clarifies entity_mode with a concrete example, mentions limit as an alias for n_results, and explains include_full's snippet vs full notes behavior. This is substantial semantic enrichment 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 'Full-text keyword search across all archive colour names and notes' with a specific verb and resource. It distinguishes itself from sibling tools by explicitly comparing to 'conceptual embedding search' with 'exact keyword matching', making its unique role obvious.

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 provides explicit usage guidance by saying it 'Complements conceptual embedding search' and even describes fallback behavior (result_path: 'direct', 'broadened', 'redirected'). The entity_mode='exact' explanation tells the agent when to use an alternative search mode, which is actionable guidance.

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

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

With the readOnlyHint annotation already declaring a safe read operation, the description adds valuable behavioral context: it is deterministic, has no LLM cost, and returns a predefined set of artifact types. This goes beyond the annotation and helps the agent anticipate the tool's reliability and output 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 three sentences long with front-loaded purpose: the first sentence names the resource, the second lists the exact outputs, and the third adds key behavioral traits (deterministic, no LLM cost). Every sentence earns its place with no wasted words.

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

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

The description thoroughly explains the tool's output scope and purpose. Given the presence of an output schema and full parameter schema coverage, the agent has enough information to select and invoke the tool correctly. It could add more detail on how optional parameters influence the pack, but this is not critical for completeness.

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

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

The schema provides 100% coverage with descriptions for all parameters, so the description does not need to elaborate. It adds no additional parameter semantics beyond what the schema already provides, but schema coverage is sufficient, making this a baseline 3.

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

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

The description clearly states the tool's function: it returns a complete brand asset pack with specific artifacts (CSS variables, Tailwind config, Figma tokens JSON, citation cards, and a Markdown brand guide). This specific verb+resource distinguishes it from sibling tools like palette_export, which focus on single asset types.

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

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

The description implies usage through phrases like 'Complete brand asset pack' and 'Everything a brand team needs to ship,' suggesting it is for comprehensive brand asset generation. However, it does not explicitly state when to use it vs. alternatives or mention exclusions, so guidance is only implied but not explicit.

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

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

Beyond the readOnlyHint annotation, the description discloses that the tool is deterministic and makes no model call, that it previously hid LLM calls causing 43-45s delays, and that certain keys are returned with interpretation_status='not_computed' plus continuation arguments. This is rich behavioral context that significantly helps the agent.

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

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

Although the description is long, every sentence adds necessary information: deterministic nature, excluded functionality, migration from hidden LLM calls, and next-step continuation. It is front-loaded with the core purpose and organized clearly.

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 covers key aspects: what is computed, what is not computed, how to proceed for interpretation, and relationships with alternative tools. It provides a complete picture for safe and effective invocation.

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

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

Schema coverage is 100% and each parameter already has a description. The tool description simply lists the parameter names without adding new format or semantics beyond the schema, so this is baseline 3.

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

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

The description clearly states the tool performs a 'brand colour audit' with specific outputs (WCAG matrix, cultural risk, CSS variables, etc.). It explicitly differentiates from siblings by noting it replaces chaining accessibility_matrix + cultural_risk_assessment and that palette_verdict is a separate follow-up call.

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 this tool for the deterministic, synchronous audit, and use palette_verdict for the interpretation (verdict, score, narrative). Names the alternative tools that it replaces, making the usage boundary clear.

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

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

Annotations already declare readOnlyHint: true, so the safety profile is covered. The description adds no further behavioral context such as limitations (e.g., not legal advice), dependencies on competitor data accuracy, or how the archive context is sourced. It does describe the return payload in detail, but that's expected behavior rather than a transparency disclosure. Given the annotation coverage, a 3 is appropriate.

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

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

Two sentences, zero waste. The first sentence front-loads the core purpose as a direct question, then the second enumerates outputs and usage context. Every clause earns its place, and the structure makes scanning easy.

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

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

Given an output schema exists and annotations are present, the description is nearly complete for a complex tool. It covers purpose, inputs, outputs, and when to use. The only gaps are minor: it does not mention potential limitations or explain 'archive context' semantics, but the output schema likely handles return structure. A 4 reflects strong completeness without being 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 each parameter is already documented with type and example. The description lists the same inputs ('brand hex, brand name, competitor hexes and names, market, region') without adding new semantic nuance or format details beyond the schema. With high schema coverage, the baseline is 3, and no extra value is provided.

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

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

The description opens with a clear, specific question that defines the tool's purpose: assessing colour ownership/collision in a market. It enumerates exact inputs and outputs, and explicitly differentiates from manual checks and competitor palette analysis. This distinguishes it from siblings like colour_compare by emphasizing market/region context and ownership verdicts.

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

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

The description states when to use the tool ('Use before committing to a brand colour in a competitive market') and what it replaces ('manual colour distance checks and competitor palette analysis'). It does not explicitly name alternative sibling tools or give exclusion criteria, but the context is clear. A 4 reflects clear usage context without explicit 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 declare readOnlyHint and idempotentHint, but the description adds meaningful context: reads an 'already-persisted, frozen brand_ref snapshot', never re-runs generation, and mutates nothing. It also discloses a critical parameter constraint ('exactly one of brand_ref or project_id') not obvious from the schema.

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

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

Three tightly packed sentences: first states purpose and output, second emphasizes read-only safety, third covers the omit-all behavior and parameter constraint. 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?

Given the presence of a full output schema and rich annotations, the description covers purpose, usage, parameter relationships, and behavioral safety. It lists the key return components (source, permitted text, restrictions, role) and explains the important 'omit claim_ids' behavior. Nothing important is missing for a read-only resolver.

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 extra meaning beyond schema: claim_ids are returned inline by sibling tools and can be omitted to return all; brand_ref and project_id are mutually exclusive (same as brand_guideline_pdf). It does not explicitly describe project_version, but the schema handles that.

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

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

The description opens with a specific verb ('Resolves') and clearly states the resource ('claim_id values') and the output components (source, text, do_not_say, claim_role). It explicitly distinguishes itself from sibling tools brand_guideline_specify and brand_guideline_select, which return these claim_ids inline.

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 that claim_ids are produced by brand_guideline_specify and brand_guideline_select, so this tool is used when you need full claim records. It also clarifies the optional 'omit claim_ids for all' behavior and references brand_guideline_pdf for the parameter acceptance pattern. No explicit 'when not to use' statement, but context is clear.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses significant behavioral traits: it reads only the frozen snapshot, never mutates the project, indicates conditional page structure (sections omitted when irrelevant), notes that derived colours are never presented as documented-source language, and clarifies that the accessibility matrix is computed upstream rather than hand-drawn. These details significantly enrich the agent's understanding of the tool's 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 front-loaded with the main purpose, but it is quite verbose. Several sentences detail the document's contents (e.g., coverage of direction, assessment, packaging, accessibility matrix) which may not be essential for tool selection or invocation. While each sentence adds some information, the description could be more concise without losing critical guidance.

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

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

Given the tool's complexity (4 parameters, conditional rendering logic, no required parameters, and an output schema), the description is remarkably thorough. It covers input constraints, selection behavior, page structure variability, safety guarantees, and preview labeling. The presence of an output schema means return value details need not be explained, and the description does not waste space on them. It is complete for an agent to correctly select and 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?

The schema already has 100% description coverage, so the baseline is 3. The description adds a crucial constraint not present in the schema: 'Accepts exactly one of brand_ref or project_id.' It also reinforces that brand_ref must be existing and ties the selection logic to brand_guideline_select. This additional meaning beyond the schema justifies a 4.

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

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

The description opens with a specific verb and resource: 'Renders a client-facing brand colour standard from an existing brand_ref.' It clearly distinguishes itself from siblings like brand_guideline_specify and brand_guideline_select by stating it is the rendering step and that it never re-runs specification or rematches archives. The scope is precisely defined.

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

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

The description gives clear usage context: it requires an existing brand_ref or project_id, and it clarifies when it produces a provisional preview versus the selected candidate. It also states what it never does ('never re-runs brand_guideline_specify, never rematches an archive'), which serves as exclusion guidance. However, it does not explicitly name alternative tools for when not to use this one, so it falls short of full alternative enumeration.

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

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

Beyond annotations (readOnly=false, destructive=false), the description discloses that the tool creates a new version under the same brand_ref, locks colours, suppresses claims, and produces a revised brand_ref. It also clarifies that suppression means marked superseded, and that reviewer states are not yet included—valuable behavioral context beyond the structured annotations.

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

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

The description is a single, dense sentence that efficiently packs purpose, inputs, outputs, and limitations without fluff. Every clause contributes meaningful information, and it remains readable despite covering multiple aspects.

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 all parameters are self-describing, the description covers the essential behavior: what is recorded, what is produced, versioning semantics, and the current scope (no approval workflow). It is complete for an agent to select and invoke effectively.

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

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

Schema coverage is 100%, with each parameter already described. The description aligns with the schema but adds limited new parameter-level detail; it reinforces the purpose of locked_colour_ids and suppressed_claim_ids but does not exceed what the schema already provides.

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

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

The description uses a specific verb ('Records') and clearly identifies the resource and action: recording a manual brand colour decision from brand_guideline_specify candidates, locking colours, and suppressing claims. It also distinguishes itself by noting the output is a revised brand_ref with a new version, and explicitly separates it from a full approval workflow.

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

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

The description implies use after brand_guideline_specify by referencing its candidate output, and states when-not using it: 'No accounts or reviewer states yet -- this demonstrates decision-making, not a full approval workflow.' It lacks an explicit alternative tool name, but the exclusion and context make usage reasonably 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?

The description extensively discloses behavioral nuances beyond annotations: the ~55s race window, the compact processing response for slow generations, the guarantee that generation continues and is never lost, and the instruction to poll with brand_guideline_status. It also exposes the nuanced evidence-floor semantics (minimum_claim_strength) and the distinction from palette_specify. This is exemplary transparency.

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-organized, with a natural flow from purpose to follow-up to timing. The TIMING section is clearly delimited and provides critical operational detail. Every sentence earns its place, though the single-paragraph format is slightly heavy; a bit more visual separation could improve scanability.

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

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

Given the tool's complexity (7 parameters, nested objects, output schema, async behavior), the description is remarkably complete. It covers the async race, fallback response, polling mechanics, follow-up tools, and the unique claim semantics. The presence of an output schema relieves the need to explain return values, but the description still covers the essential non-obvious behavior.

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 57%, so the description compensates with key semantic distinctions. The description adds meaning to minimum_claim_strength by clarifying it is an evidence floor, not a design admission filter, and that the difference from palette_specify matters. It also contextualizes the palette_input modes within the archive-grounding workflow. However, it does not systematically elaborate on every parameter, so a small gap remains.

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: generating a case for brand colours with three archive-grounded candidate palettes, distinctiveness scoring, and accessibility checks. It distinguishes itself from sibling tools by naming brand_guideline_claims, brand_guideline_select, and brand_guideline_status as follow-ups. The verb 'Generates' plus specific resource ('brand colour standard') makes the purpose unmistakable.

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

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

The description gives explicit when-to-use and follow-up guidance: 'Follow with brand_guideline_select to record which candidate was chosen' and 'resolve those into full source/permitted-claim/do_not_say text with brand_guideline_claims'. It also provides a direct alternative contrast: 'Note this differs from palette_specify, where the floor IS a hard admission filter.' This clearly orients the agent on when to use this tool vs related ones.

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 readOnly/idempotent/non-destructive, and the description adds crucial context: it never re-runs generation, and it details all possible return states (processing, complete, failed) plus the structured BRAND_JOB_NOT_FOUND error for unknown/expired refs. This exceeds what annotations alone convey.

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

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

The description is dense but front-loaded with the core purpose. All sentences add value, though the third sentence is lengthy. It is appropriately sized for the complexity of the tool.

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

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

The description fully covers the tool's role, all status values, error handling, and the correct follow-up workflow with sibling tools. Given the output schema exists, this is complete.

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

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

The schema covers 100% of the parameter semantics ('The brand_job_ref returned by brand_guideline_specify's processing response'). The description repeats this and adds the notion of expiry, but the schema already tells the agent where the ref comes from. Baseline 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 identifies the tool as a status lookup for async brand_guideline_specify jobs, using the verb 'resolves' and specifying the resource (brand_job_ref). It distinguishes itself from sibling tools by explaining it is a read-only, in-process lookup that never re-runs generation, and it points to brand_guideline_select/pdf/claims for full detail.

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

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

The description explicitly states the triggering condition ('when its race-to-complete window elapsed before generation finished') and directs users to alternative tools for full detail after completion. This provides clear when-to-use guidance and names specific sibling tools as 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?

With readOnlyHint annotation already conveying safety, the description adds useful behavioral context: it explains the tool is a composite that aggregates outputs from multiple sub-tools and mentions the internal 'Two Claude calls' detail. It also lists the full set of outputs, giving transparency into what the report includes. No contradiction with annotations is present.

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 structured with clear 'Input:' and 'Output:' sections and a final usage sentence. It is front-loaded with the main concept, and while the output list is long, each item is relevant and earns its place. It is not verbose or repetitive, and it avoids unnecessary fluff.

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

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

Given the tool's complexity (7 parameters, output schema, nested objects), the description covers inputs, outputs, and usage guidance, making it reasonably complete. The existence of an output schema means it does not need to detail return structures. It could optionally mention more about prerequisites or limitations, but overall it provides sufficient context for an agent to decide and 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?

The input schema has 100% coverage, with each parameter described in detail. The description itself lists the inputs ('hex + brand context + markets + medium + product type') but adds little semantic value beyond grouping them. It does not provide additional format, constraints, or relationships to outputs that aren't already in the schema. Thus, a baseline score of 3 is appropriate.

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

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

The description clearly states it is a 'complete brand colour intelligence report' with a specific verb ('report') and resource ('brand colour intelligence'). It explicitly differentiates from sibling tools by naming them: 'colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief', and positions itself as the composite alternative. This is a strong, specific purpose statement.

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 guidance: 'Use this instead of chaining ... separately' and mentions 'Two Claude calls total. One complete response.' This tells the agent when to choose this tool over chaining individual tools. However, it does not explicitly state when NOT to use it (e.g., when only one specific output is needed), so it falls short of a perfect 5.

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

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

Beyond the readOnlyHint annotation, the description adds 'Deterministic. No LLM cost.' which helps set expectations about consistency and cost. It also lists the specific return categories, giving a transparent view of behavior, though it omits details like response size or pagination.

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 waste. The key value proposition is front-loaded in the first sentence, and the second lists outputs and qualifiers 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?

The tool is complex with five parameters and a rich output schema, and the description covers the main purposes and output categories. The presence of an output schema reduces the need to enumerate return values, and the deterministic/no-cost traits add completeness. It could mention edge cases like market-specific outputs, but the schema covers 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?

The schema already describes all five parameters with 100% coverage. The description does not delve into parameter interactions, but it indirectly reinforces that palette is the core input. 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 explicitly states the tool provides a 'Complete brand colour system in one call' and enumerates specific outputs (colour roles, light/dark mode maps, typography guidance, usage rules, design tokens, citation cards). This clearly distinguishes it from siblings like colour_card or palette_export, which focus on narrower scopes.

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 phrase 'in one call' implies a comprehensive alternative to piecemeal tools, giving clear context for when to use it. However, it does not explicitly name sibling tools or provide when-not-to-use guidance, so it falls short of a 5.

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

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

The readOnlyHint annotation already signals safe read-only behavior, and the description adds value by specifying the exact kind of data returned (hex, archive, provenance, cultural notes). It does not introduce contradictions or hidden side effects, making the behavior clear for a lookup tool.

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

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

The description is a single, well-structured sentence that front-loads the primary action and outcome. It contains no filler or repetition, earning its place 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?

Given the presence of an output schema, a readOnlyHint annotation, and detailed parameter descriptions, the concise description is largely sufficient. It could benefit from a note about fallback behavior when a name is not found or when to prefer slug over name, but the current coverage is adequate for straightforward usage.

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 provides 100% coverage with clear descriptions for both parameters (name and slug), including the suggestion that slug is preferred. The tool description adds no additional parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('look up') and resource ('named colour') and lists the return contents (hex, archive, provenance, cultural notes). It distinguishes itself from colour_* siblings by focusing on details by name, though it doesn't explicitly differentiate from similar lookup tools like colour_passport.

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

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

The description implies when to use the tool ('when you have a named colour'), but it does not provide explicit guidance on when to use it vs alternatives or mention prerequisites like using archive_search to obtain a slug. No exclusions or alternatives are noted.

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

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

The annotation readOnlyHint=true already indicates a safe read operation. The description adds meaningful behavioral context by specifying the tool returns harmony type, clash warnings, contrast summary, and deployment rules. No side effects are disclosed because none exist, and this is consistent with 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 one sentence, front-loaded with the action verb 'Assess' and the resource, followed by a compact list of return categories. Every clause adds value and there is 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?

With only two well-documented parameters, an output schema present, and a read-only annotation, the description sufficiently covers the tool's purpose, scope, and outputs. The return details are handled by the output schema, and the description provides the needed situational context.

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

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

Schema coverage is 100%: both parameters (colours and context) are described with details like hex values and allowed contexts. The description repeats this information without adding new semantics such as default behaviour, hex format specifics, or validation rules. Baseline 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 uses the specific verb 'Assess' and identifies the resource as '2-5 colours as a combination' for a defined context list (UI, data viz, fashion, interior, print, branding). It enumerates return types (harmony type, clash warnings, contrast summary, deployment rules), distinguishing it from sibling tools like colour_compare or palette_generate.

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

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

The description clearly states when to use the tool: evaluate a combination of 2-5 colours for a given context, listing six specific contexts. It does not name alternative tools or state exclusions, but the context list and 'combination' scope imply appropriate usage. This is clear context without explicit 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 already discloses non-destructive behavior. The description adds meaningful behavioral context by enumerating the return content — LRV, chroma, hue angle, warmth, CIEDE2000 distance, and cultural context — and notes the tool's decision-support function, going 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?

Three sentences, front-loaded with the core action, followed by output details and usage guidance. Every sentence contributes distinct information: what it does, what it returns, and when to use it. No filler or repetition.

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

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

With a simple 2-parameter interface and an output schema present, the description is fully sufficient. It explains the tool's purpose, output categories, usage contexts, and explicitly rejects the harmony-tool role. An agent can confidently select and invoke this tool without ambiguity.

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 hex_a and hex_b described and example formats provided. The description phrases them as 'any two hex values,' reinforcing the relationship between parameters, but does not need to add further detail since the schema already carries the semantic load.

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

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

The description opens with a specific verb and resource: 'Deep perceptual and semantic comparison between any two hex values.' It lists concrete output dimensions and clearly distinguishes itself from harmony tools with 'Not a harmony tool — this is a decision and reasoning tool,' setting it apart from siblings like 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?

Provides explicit guidance: 'Use when choosing between two colours or explaining why one works better than another.' It also states an exclusion ('Not a harmony tool'), which helps an agent decide against this tool when harmony-related tasks arise.

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 context beyond annotations by explaining the tool handles both hex and palette inputs and that it serves as a component of colour_passport. No contradictions, and it clarifies scope without needing to restate safety since annotations cover that.

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, then a concise usage comparison. Every sentence carries meaning with zero 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 readOnly annotation, output schema, and full parameter coverage, the description sufficiently addresses what the tool does, when to use it, and how it relates to colour_passport. It is complete for an agent to select this tool among many colour-related siblings.

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

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

Schema descriptions cover all 3 parameters at 100%, so the baseline is 3. The description connects 'hex value or palette' to the hex/palette parameters but does not add per-parameter syntax or nuance beyond what the schema already provides.

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

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

The description clearly states the tool assesses cultural risk for a hex value or palette, enumerating specific dimensions (symbolic weight, taboos, religious associations, market flags). It explicitly distinguishes itself from colour_passport by positioning as a component and direct-call for palette-level risk 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?

Provides explicit guidance: 'Use colour_passport for a general profile; call this directly for palette-level risk checks or when cultural risk is the only thing being asked about.' This names an alternative and gives concrete decision 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 already provide readOnlyHint=true, covering safety. The description adds that it is a 'semantic fingerprint' and a component of colour_passport, but does not elaborate on output behavior, limitations, or side effects beyond that. 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, front-loaded with the core purpose, and no unnecessary words. Every sentence contributes to purpose or usage guidance.

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

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

For a simple one-parameter read-only tool with an output schema, the description fully covers what, when, and why. It references its relationship to colour_passport and provides a clear usage condition. The meaning of 'semantic fingerprint' is likely explained by the output schema, so no further detail 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% and the parameter description includes a format example ('#4A2A50'). The tool description only reiterates 'single hex colour', adding no new semantic detail beyond the schema, so the baseline 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 states the tool produces a 'compact semantic fingerprint' for a single hex colour, using a specific verb and resource. It directly distinguishes itself from colour_passport, making the purpose unmistakable 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?

Explicitly instructionates when to use this tool versus colour_passport: 'Use colour_passport for a general colour profile; use this only when the user explicitly wants the fingerprint format alone.' This names the alternative and provides a clear condition.

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

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

Even with readOnlyHint annotation, the description adds substantial behavior: verdict types (yes/conditional/avoid), risks, required actions, illuminant analysis, substrate notes, and recommended alternatives. It also discloses methodology (CIEDE2000 archive matching and Claude material knowledge), going well beyond the annotation.

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

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

The description is concise, with a clear front-loaded purpose and a compact list of returns. The final 'Backed by...' sentence adds credibility but is not purely functional, and the four examples are useful though slightly expand length.

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

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

The description covers purpose, output categories, methodology, and concrete usage scenarios, and is paired with a full output schema and readOnlyHint. It is sufficiently complete for correct invocation despite the tool's complexity and the large sibling set.

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

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

Schema description coverage is 100% for all 5 parameters, so the baseline is 3. The description does not add parameter-specific syntax or details beyond what the schema provides, though its examples reinforce valid substrate and orientation values.

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

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

The description clearly states the tool assesses whether a hex colour can be safely specified for a physical application, using a specific verb and resource. It distinguishes itself from colour_verdict or colour_metrics siblings by focusing on physical/material safety rather than generic colour analysis.

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

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

It provides clear usage context: use when assessing safety for a physical substrate, reinforced by concrete examples like 'ultramarine on lime plaster' and 'lead white on exterior timber'. However, it does not explicitly mention alternatives or exclusions, which prevents a 5.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it is a read operation. The description adds a small detail about matching against named archive colours, implying a lookup dependency, but it does not disclose edge-case behavior or data requirements. This is moderate added context beyond annotations.

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

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

The description is a single concise sentence that immediately states the action and the range of outputs. Every word earns its place, with no fluff or repetition.

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 read-only annotation, full schema coverage, and presence of an output schema, the description does not need to explain return formats. It explains the specific harmony types and the archive matching. A minor gap is the lack of detail about how archive matching works or failure behavior, but it is sufficient 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% with descriptions for both parameters. The description adds value by enumerating the harmony types (complementary, triadic, etc.), which hints at valid values for harmony_types, but it does not clarify default behavior when the optional parameter is omitted. It aligns with the schema but adds only minimal extra meaning.

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

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

The description clearly states the tool returns specific colour harmonies (complementary, triadic, analogous, split-complementary) matched to named archive colours. This is a specific verb+resource and distinguishes it from sibling tools like colour_combination 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 when harmonious colour schemes are needed, but it does not explicitly state when to prefer this tool over alternatives like colour_combination. No exclusions or alternative tool references are provided, leaving usage context implied rather than explicit.

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

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

Annotations only state readOnlyHint: true. The description adds valuable behavioral context by disclosing that outputs are 'backed by the nearest archive colour's cultural provenance' and that the tool is tunable by audience and tone. This goes beyond the annotation's simple safety hint and explains what the tool actually does with inputs.

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 that front-load the primary action and outputs, followed by concise use cases. No wasted words; every sentence earns its place. This is an example of efficient, well-structured tool documentation.

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 generative nature, the description lists all output types (hook, story, tweet, image prompt, follow-up questions) and presents relevant usage scenarios. An output schema exists to detail return values, so the description does not need to cover those. The description is complete for an agent to decide 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% with clear descriptions for hex, tone, and audience. The description's mention of tunable audience/tone examples ('general public, designers, historians, children') largely mirrors the schema's own examples. It adds minimal extra meaning, such as 'any hex colour', which does not significantly exceed what the schema already conveys.

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

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

The description opens with a specific verb ('Generate') and lists concrete outputs (hook sentence, three-sentence story, tweet, image prompt, follow-up questions) for a hex colour. It clearly distinguishes this tool from siblings like colour_story or colour_namer by focusing on multi-format content generation grounded in archive provenance.

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 ('Use to make archive colours shareable, to generate content, or to power a public-facing colour chat experience'), giving clear context for when to invoke it. It does not explicitly mention when not to use it or name alternatives, so it falls short of a 5 but is well above vauge guidance.

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

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

The readOnlyHint annotation already declares this as a safe operation. The description adds value by specifying the brand scope ('Farrow and Ball and Little Greene'), which is not in the annotation. However, it does not clarify whether the tool supports additional brands beyond these two, and the 'including' wording could be ambiguous. The behaviour of matching a hex to a named colour is clear.

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

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

The description is a single sentence that is front-loaded with the verb and resource, containing no filler. It efficiently conveys the essential purpose.

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

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

The tool has low complexity, a complete input schema, an output schema, and a readOnlyHint annotation. The description covers the core purpose and specific brands. It is slightly ambiguous about whether other paint brands are supported, but the overall context is sufficient for an agent to understand what the tool does and what it 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 description coverage is 100%, with each parameter already having clear descriptions (n: 'Number of matches', brand: 'Optional brand filter', hex_val: 'Hex value'). The description does not need to add parameter details. It does not go beyond the schema, but that is acceptable given the high coverage.

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

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

The description clearly states the tool's function: 'Find the nearest named colour in commercial paint systems including Farrow and Ball and Little Greene.' This uses a specific verb ('find') and resource ('nearest named colour in commercial paint systems'), and explicitly names the included brands, which distinguishes it from sibling tools like colour_namer or colour_compare that may handle generic colour naming or 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 usage for matching a hex value to a commercial paint system colour, which is clear context. It does not explicitly list alternatives or when-not-to-use, but the mention of 'commercial paint systems' and specific brands provides sufficient guidance for selection among the many sibling palette/colour tools.

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

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

The annotation readOnlyHint=true already covers safety, and the description adds context beyond that by specifying the exact metrics returned and the single-colour scope. This helps set expectations for the response without contradicting the annotations.

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

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

The description is two concise sentences, front-loaded with what the tool returns, followed by usage guidance. Every sentence serves a purpose 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 simple single-parameter input, the presence of an output schema, and a read-only annotation, the description fully covers scope and usage. It is complete and leaves no significant gaps for an agent to guess.

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

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

The schema has 100% coverage for hex_val with a clear type and example. The description does not add parameter-specific details beyond what the schema provides, so the baseline 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 states the tool 'Returns raw perceptual metrics (LRV, chroma, hue angle, warmth, undertone) for a single colour', using a specific verb and resource. It distinguishes itself from siblings by explicitly positioning it as 'one component of colour_passport' and contrasting with 'colour_passport' for general profiles.

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

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

The description provides explicit when-to-use guidance: 'Use colour_passport for a general colour profile; use this only when the user explicitly wants isolated numeric values.' This directly addresses alternatives and sets clear exclusions, making it easy for an agent to select the right 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 annotation readOnlyHint=true is consistent with the description, which adds rich behavioural context: the CIE Lab subtractive model, perceptual accuracy, and the nature of the output (nearest archive match with cultural context). This goes well beyond what the annotation alone conveys.

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

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

Four sentences, each earning its place: the core function, the output, the model reinforcement, and a concrete example. It is front-loaded with the most important information and has no fluff.

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

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

The description covers purpose, method, output, and a worked example. Given the existence of an output schema and annotations, it is complete without needing to detail return structures or safety profile.

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 semantic value through the example (Prussian Blue + Yellow Ochre gives a muted green), illustrating the intended meaning of the hex inputs as pigment colours. This helps the agent understand the parameters beyond their raw format.

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

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

The description states exactly what the tool does: simulate subtractive mixing of two colours in CIE Lab space, distinct from RGB screen blending, and returns the mixed hex plus nearest archive match. This is a specific verb+resource+method and distinguishes it from other colour tools.

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

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

It explicitly notes 'not RGB screen blending', which is a clear when-not situation. However, it does not name alternative tools for additive mixing or colour comparison, leaving the guidance slightly implicit. The example provides a concrete use context but no explicit 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, so the safe, read-only nature is already known. The description adds useful behavioral context beyond that: names are 'archive-verified' and 'grounded in a real archive source,' and it lists the naming styles. It does not contradict annotations, and it supplements them with meaningful details about the tool's 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 three concise, front-loaded sentences. The first sentence states the core action, the second lists options, and the third explains the unique value and primary use case. There is no filler or repetition; every sentence contributes.

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

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

Given the tool's complexity (5 parameters, 1 required) and the presence of an output schema, the description is adequately complete. It covers purpose, style options, archive grounding, and a concrete use case. It could mention when to prefer alternative tools, but that is more of a usage guideline matter.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lists the style options ('geographical, poetic, material, literary, botanical, industrial, or mixed'), which mirrors the schema's style property but adds no extra meaning. It does not elaborate on parameters like market, n_names, or product_type, relying on the schema to carry that 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 function: 'Generate memorable, archive-verified colour names for any hex value.' It uses a specific verb ('Generate'), a specific resource ('colour names'), and adds scope ('for any hex value') and differentiators ('archive-verified', 'grounded in a real archive source'). This distinguishes it from sibling tools like colour_card or palette_generate, which focus on palettes or analysis rather than naming.

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

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

The description provides a clear context: 'The core of the Shopify product naming use case,' implying when the tool is appropriate. However, it does not explicitly mention when not to use it or compare it to sibling naming tools like ecommerce_namer, so it lacks exclusions or 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 the description does not contradict and actually supports by describing a read-style retrieval. The description adds rich behavioral context by listing the exact domains of information returned (colour science, archive anchor, provenance, physics, cultural reading) and stating its canonical/single-call nature, exceeding what annotations alone convey.

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

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

The description is logically structured: opening definition, content enumeration, usage instruction, and examples. It is somewhat verbose but each sentence adds productive detail (e.g., specific examples). The length is justified by the tool's comprehensive nature, though it could be tightened without losing 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?

Despite the tool's high complexity, the description gives a thorough overview of the returned data and its role in the tool ecosystem. Since an output schema exists and the description outlines the major return categories, it provides enough context for an agent to select and invoke the tool appropriately. The examples clarify input expectations and output anchoring.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-level meaning beyond the schema; it only includes example hex values which are illustrative but not semantically additive. The description mentions the equivalent of parameters (hex values) but does not clarify the other fields, though the schema already handles that.

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

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

The description states a specific verb ('Returns') and resource ('everything known about a hex value'), enumerating the exact categories of data. It clearly distinguishes itself from siblings by declaring it the canonical foundation call and explicitly naming the tools it replaces (colour_dna, archive_provenance, etc.), making its scope and role unmistakable.

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

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

The description explicitly says to 'Use this as the foundation call when you need the complete picture' and contrasts it with chaining multiple separate tools, naming those alternatives. This gives clear when-to-use guidance and identifies the alternative approach for more granular needs.

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

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

Annotations only provide readOnlyHint=true. The description adds behavioral details such as the 20-value limit, automatic deduplication, and the full set of returned fields (colour science, archive anchor, evidence grade, etc.). This goes beyond the annotation without contradicting it.

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

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

The description is compact and front-loaded. The first sentence names the tool as a batch version, then immediately states the limit and return behavior. Every sentence adds value with no redundant wording.

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 and full schema parameter descriptions, the description covers the core purpose, constraints, deduplication, and usage scenarios. It is complete for a batch lookup tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a maximum batch size of 20 hex values and states that deduplication occurs, which are constraints not present in the schema. It does not discuss the optional parameters, but those are fully described in the schema.

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

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

The description explicitly states it is the 'Batch version of colour_passport' with a clear verb 'submit' and resource 'hex values', and lists the returned product. It distinguishes itself from the singular colour_passport sibling by batching up to 20 values.

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: 'multi-colour workflows, Figma palette analysis, or any case where calling colour_passport separately for each colour would be slow.' This provides clear context and names the alternative (colour_passport), though it does not explicitly list 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, establishing the safe read-only nature. The description adds valuable behavioral context by explaining that the name source is archive-grounded and uses dE2000 distance for color matching, which helps the agent anticipate how results are produced. No contradictions with annotations.

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

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

The description is two sentences with no redundancy. The first sentence front-loads the action and lists all output formats; the second provides the naming source. Every word earns its place, making it highly efficient.

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

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

The description, combined with a complete input schema and the presence of an output schema, provides sufficient context for a read-only transformation tool. It lacks explicit edge-case handling (e.g., invalid hex) and prerequisites, but these are not critical given the tool's simplicity and the schema coverage.

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%, as both hex and archive parameters are already described in the input schema. The description mentions 'hex value' and 'Archive-grounded' which loosely connects to the archive parameter, but it adds no new parameter-specific meaning beyond what the schema already provides.

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

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

The description states a specific action (return every developer token format) for a given hex value, listing concrete outputs (CSS variable, kebab-case, camelCase, PascalCase, Tailwind class, TypeScript const, SCSS variable). This clearly distinguishes it from sibling tools like colour_namer by focusing on developer token formats and mentioning archive-grounded naming with dE2000 distance.

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 developers need naming conventions from a hex value, but it does not explicitly state when to prefer this tool over alternatives or provide exclusions. No alternative tools are mentioned, so usage context is only implied, not explicit.

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

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

The annotation already indicates read-only behavior, and the description does not contradict it. The description adds valuable context by specifying what the narrative contains (history, civilisations, archive names) and provides a concrete example. It does not discuss potential latencies or edge cases, but the output schema and read-only hint lower the burden.

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

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

The description is three sentences: what it does, when to use it, and an example. It is concise, front-loaded with the core purpose, and every sentence earns its place. No fluff or redundancy.

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

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

Given the presence of a complete input schema, an output schema, and a read-only annotation, the description needs only to convey the tool's purpose and when to use it. It does so effectively, including a rich example. There is no significant missing information for a tool of this moderate complexity.

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

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

The input schema has 100% description coverage for both parameters, so the baseline is 3. The description does not add much beyond the schema—it repeats the hex requirement via the example but does not elaborate on n_archives or how it affects the output. The schema already documents the parameters adequately, and the description adds minimal additional value here.

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

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

The description uses a specific verb ('returns') and clearly identifies the resource and scope ('cultural story of a colour'), describing exactly what the tool does. It also distinguishes this from siblings like colour_timeline or colour_dna by focusing on the narrative and historical journey. The concrete example reinforces the purpose.

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

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

The description gives clear use cases ('image generation prompts, brand storytelling, and creative briefs') which indicate when to apply the tool. However, it does not explicitly state when not to use it or mention alternative tools for other colour-related analyses, so it falls short of a 5 but 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?

With readOnlyHint=true already disclosing the non-destructive nature, the description adds meaningful context about what the tool produces: a report with verdict, strategy summary, archive anchor, market readings, usage rules, and copy hooks. This goes beyond the annotation by explaining the actual deliverable, though it doesn't detail any internal processes 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 information-dense but well-structured, opening with a clear one-line purpose then organizing inputs, outputs, and examples. It is somewhat long due to the many output fields listed, but every sentence contributes meaningful information. The front-loading of 'Single-call commercial colour strategy report' is effective.

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

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

Given the tool's complexity, the description covers all essential aspects: it explains what the tool does, what inputs are needed, what outputs to expect, and provides representative use cases across industries. An output schema exists, so detailed return-value documentation is unnecessary. The description is sufficiently complete for an agent to decide when and how to invoke this tool.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description's input summary mostly restates the schema structure (brand_context with categories, constraints with avoid/must_work_on), but it adds helpful examples like 'luxury fragrance brand UK/France/Japan' that clarify intended parameter usage. No additional syntax or relationship details are provided beyond the schema.

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

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

The description opens with 'Single-call commercial colour strategy report'—a specific verb and noun combination that clearly defines the tool's purpose. It then distinguishes itself from sibling tools by enumerating the combined components ('archive grounding, verdict, brand fit, market risk...'), making it obvious this is the comprehensive strategy option rather than a single-purpose tool.

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

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

The descriptor 'Single-call' and the list of combined analyses clearly signal when to use this tool (when a complete strategy report is needed in one call) versus using individual sibling tools like colour_verdict or colour_hooks. It provides clear context and examples of suitable use cases, though it doesn't explicitly state 'use instead of X' or 'don't use when Y'.

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 meaningful behavioral context beyond the readOnlyHint annotation by explaining that the output is a dated sequence of archive entries with primary sources, emphasizing chronological ordering and cultural/historical scope. It does not mention limitations like pagination or failure cases, but with the annotation and output schema, this is sufficient. 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 well-structured and front-loaded with the tool's core function. Each sentence earns its place, including the illustrative example that clarifies the concept and shows the historical trace. It is appropriately sized without unnecessary filler.

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

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

Given the tool's low complexity (2 params, 1 required), full schema coverage, existing output schema, and readOnlyHint annotation, the description is complete for an agent to select and invoke the tool correctly. It covers purpose, usage, return format, and an example, leaving no significant 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?

The input schema already provides full descriptions for both parameters (concept and n) with 100% coverage. The description adds an example (indigo) that illustrates the concept parameter, but does not provide additional syntax or semantic details beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: given a concept or colour name, it traces documented appearances chronologically across cultures and centuries, returning dated archive entries with primary sources. This specific verb+resource+scope distinguishes it from sibling tools like colour_story or archive_provenance, and includes a concrete example for the 'indigo' concept.

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 for historical research, provenance chains, and understanding why a colour carries the cultural weight it does.' This provides clear context on when to use the tool, but does not explicitly list alternative tools or exclusions, which would merit a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds behavioral context by detailing the types of data returned (historical variants, lighter/darker versions, cultural siblings), 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 sentences, front-loaded with the core function and a brief context for designers. Every word earns its place, with no 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?

With a simple one-parameter tool, output schema present, and a read-only annotation, the description fully covers purpose and usage. It explains what the tool returns and who it's for, making it complete for the given complexity.

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

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

The schema already has 100% coverage for the 'name' parameter, describing it as a 'Named archive colour e.g. Bourton Honey.' The description merely restates this ('For any named archive colour') without adding significant new meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'return historical variants, lighter and darker versions with archive matches, and cultural siblings' for a named archive colour. This specific verb+resource phrasing distinguishes it from sibling tools like colour_compare or colour_harmonies.

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

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

The description provides clear context for when to use the tool: 'Essential for designers exploring around a colour.' It does not explicitly name alternatives or exclusions, but the use case is well implied.

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

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

The description discloses valuable behavioral context beyond the readOnlyHint: it explains that the tool is 'Backed by CIEDE2000 archive matching and Claude cultural intelligence' and lists what the output includes ('strengths, risks, avoid-if scenarios, and better alternatives'). This adds a methodological understanding and sets expectations without contradicting the read-only annotation.

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

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

The description is concise and front-loaded: the first sentence states the core purpose, followed by the output verdicts, content included, underlying method, and relevant examples. Every sentence contributes value without redundancy, and the structure is easy to scan.

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

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

For a tool with 5 parameters, an output schema, and a readOnlyHint, the description is remarkably complete. It covers purpose, output values, output contents, methodology, and practical examples, leaving no major gaps. The presence of an output schema means return values need not be described in detail, and the description does not over-explain.

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

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

Schema description coverage is 100%, and the schema already documents each parameter (hex, medium, markets, audience, use_case). The description's examples (e.g., 'luxury hotel brand in Japan') illustrate how parameters combine but do not add new semantic meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Evaluate a hex colour for a specific use case, market, and medium.' It specifies a decisive verb (Evaluate) and the resource (hex colour), and goes beyond by explicitly naming the three possible verdicts (use_with_confidence, use_with_caution, avoid), distinguishing it from sibling tools that assess other aspects like cultural risk or palettes.

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

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

The description conveys when to use the tool through its focus on evaluating a colour for a specific use case, market, and medium, and it provides illustrative examples. However, it does not explicitly mention when not to use it or compare it with alternatives like colour_cultural_risk or palette_verdict, so it lacks explicit exclusions but gives a clear context.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict that. The description adds behavioral context by explaining it is a compound tool that replaces chaining multiple other tools and lists the full set of delivered outputs. It does not mention possible latency or resource usage, but the read-only annotation lowers the burden.

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

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

The description is compact yet information-dense. It front-loads the 'compound tool' nature, enumerates the outputs, lists the chained tools it replaces, and provides explicit when/not-to-use guidance. Every sentence earns its place without redundancy.

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

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

Given the tool's complexity, the description covers the purpose, outputs, usage context, and exclusions. An output schema exists, so return values are already documented. The read-only annotation is present, and the description's scope is fully adequate for an agent to select and invoke the tool correctly.

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

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

Input schema has 100% description coverage, so the baseline is 3. The description's mention of 'audience' is not represented in the schema, which is a minor mismatch, but the schema itself adequately documents all parameters. The description does not add significant parameter-level information beyond what the schema already provides.

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

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

The description clearly states it is a 'One-call compound tool' that submits concept, medium, audience, and constraints and receives a complete design package. It lists concrete outputs and explicitly distinguishes itself from individual sibling tools by saying it 'Replaces chaining' several specific 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?

Provides explicit usage guidance: 'Use when an AI agent or user needs a complete, deployable colour direction in a single call.' It also gives a clear exclusion: 'Not for iterative refinement — use individual tools for that.' This effectively differentiates when to use this tool versus alternatives.

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

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

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: copy is grounded in archive provenance, colour names come from the nearest archive match rather than being invented. This goes beyond the annotation by explaining the underlying data source and generation philosophy, providing useful transparency about the tool's behaviour.

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

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

The description is compact and information-dense, covering what it does, inputs, outputs, unique value, examples, and use cases in a single paragraph. Every sentence adds value, and the most important action is stated first. It avoids unnecessary fluff.

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

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

The description provides a thorough overview of the tool's purpose, inputs, outputs, examples, and applicability. Given the output schema exists and there are no complex side effects or destructive actions, the description is nearly complete. It could mention edge cases like unavailable archive matches, but that is not essential for basic usage.

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 reinforces parameter purposes through examples (velvet cushion, ceramic vase, linen throw) and mentions the input combination (hex + product type + tone + channel). It does not add significant new semantic detail beyond what the schema already documents, but the examples provide practical context.

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

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

The description clearly states the tool generates complete ecommerce product copy from a hex colour, listing specific inputs and outputs. It distinguishes itself from sibling tools like ecommerce_namer by covering full copy (titles, descriptions, SEO, social) rather than just naming.

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 gives clear context for use ('Directly useful for Shopify, WooCommerce, and editorial product pages'), implying suitable scenarios. However, it does not explicitly exclude alternatives or state when not to use this tool versus other colour/copy 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 provide readOnlyHint=true, so safety is already declared. The description adds meaningful behavioral context: every name is 'archive-sourced, not invented' and carries a defensible citation. It also states the 40-SKU limit. These go beyond the annotation without contradicting it.

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

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

The description is compact and front-loaded with the core action. It covers input, output, and use cases in a few sentences. The redundancy between 'Every name is archive-sourced, not invented' and the following citation sentence is minor but slightly bloats the text.

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

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

For a tool with 5 parameters, an output schema, and read-only annotations, the description is complete: it states the input types, output format, use cases, and quality guarantees. It does not explain the behaviour of max_dE, but the schema describes it, so the gap is acceptable.

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

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

Schema coverage is 100% and parameter descriptions are self-sufficient. The description repeats some parameter names (hexes, style, brand, category) and mentions style options already in the schema, but adds no new meaning beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource+constraint: 'Generate archive-grounded colour names for up to 40 product SKUs.' It clearly distinguishes from siblings like colour_namer by emphasizing 'archive-grounded' and the ecommerce context, and it enumerates the exact output fields.

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 names target use cases ('Use for paint ranges, candle collections, fashion lines, homeware, cosmetics'), giving clear context. However, it does not state when to avoid this tool or name alternatives such as colour_namer, so it lacks the when-not/exclusion guidance for a 5.

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

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

The description discloses that it uses a 'proprietary k-means++ algorithm', returns 'hex values with proportional weights', and clarifies that image_id is ephemeral (returned by ingest_image). The readOnlyHint annotation already covers the non-mutating guarantee, so the bar is lower, and the description adds meaningful context beyond that (algorithm, return format, optional archive matching). It could add pagination/limit behavior or error cases but is solid.

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

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

The description is a single focused paragraph with clear logical flow: primary function → input prerequisites → fallback workflow → output → optional feature → sequencing. Every sentence earns its place with no filler. It's slightly dense, which is why it doesn't get a 5, but there is zero waste.

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 (so return values are documented there), the complexity is well covered: it handles the dual-input scenario (URL vs upload), the ingest_image fallback, optional analysis features, and the relationship to sibling tools. The 7-parameter tool with nested objects is fully addressed. Genuinely 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 schema fully documents all 7 parameters. The description adds value by explaining the relationship between image_url/image_id (that image_id comes from ingest_image and is ephemeral), and the style_context's purpose for coherent cultural naming (also present in schema). The description reinforces but doesn't go far beyond the schema's own parameter descriptions, 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 tool extracts dominant colours from a photograph using a specific algorithm (k-means++), distinguishes it from siblings by mentioning the ingest_image prerequisite workflow, and positions it relative to image_brief ('Use this before image_brief'). The verb+resource is specific and the tool's role in a multi-step pipeline is 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 explicitly explains when to use this tool vs alternatives: it requires a public image_url OR image_id, and explicitly instructs calling ingest_image first if the user only has a raw file with no public URL. It also names the alternative (image_brief) and states sequencing ('Use this before image_brief'). This is exemplary usage 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?

Beyond the readOnlyHint annotation, the description discloses rich behavioral details: grouping_basis and provenance_credit reporting, the provenance vs perceptual similarity grouping logic, that historical claims are templated only from documented fields, that room/surface assignment is editorial, and that the response can be 60-100KB+ requiring house_ref for PDF rendering. This fully informs the agent of side effects and output 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?

Although long, the description is well-structured and every sentence earns its place. It is front-loaded with the core purpose, then covers grouping, provenance reporting, example, alternative tool, and output handling. No fluff; all content is operational guidance.

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 covers all necessary context: usage, example, alternative, output size, and downstream handoff. It does not need to repeat return schema details, and it offers critical practical information about response size that agents would otherwise miss.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing a full example of the rooms array and clarifying nuances like orientation not affecting palette selection and invalid archive names yielding clear errors. This goes beyond the schema's own field descriptions.

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

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

The description opens with a specific verb and resource: 'Generate a complete multi-room house colour scheme from a single archive.' It clearly distinguishes from sibling interior_specify by noting the multi-room grouping scope and explicitly directs single-room use to that alternative.

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 provides explicit when-to-use guidance, a concrete example, and names the alternative tool ('Use interior_specify instead for a single room without cross-room grouping'). It also explains how to pass the response's house_ref to palette_pdf, covering downstream usage.

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 declare readOnlyHint=true, so safety is covered. The description goes well beyond this by disclosing the compound internal behavior: colour extraction, archive matching with cultural naming, scene understanding, style period identification, product category suggestions, prompt generation, and swatch URL return. 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?

Three sentences, front-loaded with a one-line summary of value, followed by concrete output enumeration and a usage pointer. Every sentence carries distinct information; 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?

For a compound tool with 8 optional parameters and an output schema, the description covers core functionality, alternatives, and style context. However, it doesn't explicitly state that one of image_url/image_base64 must be supplied despite 'one image in' suggesting it; with zero required params in schema, this could leave an agent uncertain about invocation prerequisites.

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 reinforces style_context examples and product categories but these mostly duplicate the schema's own parameter descriptions (style_context already lists the same examples). It adds no new syntax, default, or relationship information beyond the schema.

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

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

Description opens with 'Compound endpoint: one image in, full creative brief out' and enumerates concrete outputs (colours, archive matching, scene understanding, style period, product directions, prompt, swatch URL). It distinguishes from siblings by explicitly recommending it over chaining palette_extract + palette_analyse + agent_brief.

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

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

Provides explicit usage guidance: 'Use instead of chaining palette_extract + palette_analyse + agent_brief separately' names the alternative workflow, and advises passing style_context with concrete examples for coherent archive matching. This clearly tells an agent when to invoke this tool over alternatives.

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

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

Annotations declare readOnlyHint=true, and the description adds valuable behavioral context: 'The image is never stored — processed in memory only' and details the algorithm (K-means++ with Bradford chromatic adaptation). These go beyond the structured annotations and disclose privacy and processing traits, though no failure modes or rate limits are mentioned.

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

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

The description is well-structured, starting with the core action and then detailing outputs, use cases, and privacy. It is slightly longer than necessary due to algorithm details, but each sentence contributes value and it remains focused. It is appropriately sized for a tool with this complexity.

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

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

Given the output schema exists and schema coverage is complete, the description covers the essential aspects: purpose, input format, use cases, algorithm, output highlights, and privacy. It does not explain every return field, but that is unnecessary with an output schema present. The tool is well contextualized for an agent.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description reinforces the base64 image input and the n_colours behavior (max 5) but does not add substantial meaning beyond the schema. It mentions archive matching generically, which aligns with the archive parameter, but no new syntax or format details are given.