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?

Annotations only declare readOnlyHint=true, so the description carries the burden of behavior — and it delivers richly: it guarantees the tool 'never returns a bare empty result' and explains the three response routing states (direct/broadened/redirected) so the agent knows which fallback fired. It also discloses the off-genus exclusion behavior of entity_mode='exact'. No contradiction with the readOnly 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?

Front-loaded with the core purpose and access patterns before any nuance. The match-count examples are concrete and useful. It is long (~230 words) and slightly overlaps the schema's entity_mode explanation, but every section earns its place for a 9-parameter tool; nothing is 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?

For a complex 9-param tool with an existing output schema, the description covers everything non-inferable: fallback behavior, result routing, entity resolution semantics, and the sibling contrast. Pagination and return values are already handled by schema descriptions and the output schema, so no burden falls on the description there. Complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by enumerating the searchable content taxonomy (material, cultural reference, pigment type, historical period) and explaining the consequence of entity_mode on result composition. Some overlap exists — entity_mode and query examples are also in the schema — but the behavioral outcomes (result_path routing, exclusions) genuinely enrich parameter selection.

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

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

Opens with a precise verb+resource statement: 'Full-text keyword search across all archive colour names and notes', then enumerates what can be found (name fragment, material, cultural reference, pigment type, historical period). Explicitly differentiates itself from conceptual embedding search, so an agent can tell it apart from query_conceptual and historical_colour_query without opening schemas.

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?

Names the key alternative ('Complements conceptual embedding search with exact keyword matching') and the selection criterion (exact keyword vs semantic). The examples and entity_mode discussion add practical guidance. It stops short of an explicit when-not-to-use statement for every sibling, but the contrast with conceptual search is clear enough for the main routing decision.

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?

The description goes far beyond the single readOnlyHint=true annotation. It discloses that the tool is synchronous and deterministic with no model call, reveals that interpretation was historically performed inside the tool without disclosure and the resulting 43-45s latency, and explains the continuation mechanism (returns palette_verdict.continuation.arguments to forward verbatim). It also discloses the PARTIAL/INSUFFICIENT audit_status behavior when site_evidence is inadequate and that the tool itself does not browse. This is exactly the kind of historical and operational transparency an agent needs. No contradiction with readOnlyHint=true — a deterministic synchronous computation is consistent with read-only.

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?

This description is long, but every sentence carries operational information an agent cannot infer from the schema or annotations. The structure is well-designed: core purpose front-loaded, then COMPUTED HERE, then NOT COMPUTED HERE, then the live-site workflow, then downstream routing. Capitalized section markers ('COMPUTED SYNCHRONOUSLY', 'NOT COMPUTED HERE', 'FOR A LIVE-SITE BRAND AUDIT') make the dense content scannable. It loses one point only because some sentences could be tightened without losing meaning; at this complexity level the length is otherwise justified.

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

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

For a tool with 6 parameters, nested objects, and an output schema, this description is remarkably complete. It covers the computation model, what is deliberately excluded and why, the continuation handoff to palette_verdict, the live-site evidence requirements with named status codes, the downloadable deliverables (PNG, PDF, ASE, JSON, CSS), and the anti-pattern to avoid (presenting archive anchors as recommendations). Since an output schema exists, return values need not be fully re-explained, but the description still names the key output keys. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema. For site_evidence it explains the workflow prerequisite (inspect rendered pages first), the minimum evidence for a FULL audit (homepage, about, one deep page, rendered evidence from at least two), and the consequence of shortfalls (PARTIAL/INSUFFICIENT status). It also adds behavioral guidance about the palette parameter ('Never present the archive anchors a colour was derived from as the colours you are recommending'). It does not add much for market, medium, use_case, or brand_category, which the schema already covers adequately.

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

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

The opening sentence states a specific verb and resource ('colour brand audit') and immediately narrows scope with 'fully deterministic' and 'no model call of any kind.' The description then enumerates precisely what is computed (WCAG matrix, cultural risk, CSS variables, Tailwind config, design tokens) and what is not (palette interpretation), which sharply distinguishes it from siblings like palette_verdict, accessibility_matrix, and cultural_risk_assessment. Even the title 'Complete Brand Colour Audit' is descriptive rather than tautological.

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?

This is exemplary usage guidance. It explicitly says the tool 'Replaces chaining accessibility_matrix + cultural_risk_assessment' and that palette_verdict is 'an explicit, optional second call rather than a hidden one,' naming both the alternatives and the relationship. It gives conditional instructions for the live-site case ('inspect representative rendered pages FIRST... a CSS scrape alone is not an audit'), and it routes downstream to palette_finalize with concrete conditions. An agent knows exactly when to call this tool, what to do beforehand, and what to call next.

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 carry readOnlyHint=true, and the description is consistent with a pure analysis tool. It adds genuine behavioral detail beyond the annotation: the verdict taxonomy (strong/viable/contested/collision), the 0-100 distinctiveness scale, and the fact that it consults archive context per colour. The provenance-based scoring caveat lives in the schema rather than the description, but the description discloses the core analytic behavior well.

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 with zero filler: purpose question, input summary, output list, usage timing, and replacement value. Dense but readable, and the most decision-relevant information (what it returns, when to use it) is front-loaded before the output enumeration.

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

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

For a complex tool with 7 parameters and an output schema, the description covers the essentials: purpose, inputs, outputs, and when to invoke. The presence of an output schema relieves the description of explaining return-value structure. Minor gaps: the meaning of 'archive context for each colour' is opaque, and the verified-vs-estimated provenance behavior is only in the schema — an agent reading only the description would miss a key scoring caveat.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters with examples (e.g., '#D4A829', 'UK luxury food retail', provenance enums). The description restates the input set at a summary level but adds no new semantic information beyond the schema. Baseline 3 is correct since the schema carries the full burden.

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

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

Opens with a purpose-framing question ('Can this brand own this colour against these competitors in this market?') that captures the exact job. Enumerates concrete inputs and outputs (CIEDE2000 distance, distinctiveness score, ownership verdict) that clearly differentiate it from sibling tools like colour_compare or colour_metrics — this is an ownership/strategy assessment, not a numeric 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?

Provides explicit timing guidance: 'Use before committing to a brand colour in a competitive market.' Also states it 'replaces manual colour distance checks and competitor palette analysis,' which frames the decision context. However, it never names a sibling alternative or states when NOT to use it (e.g., when only raw CIEDE2000 numbers are needed), so it stops short of full exclusion guidance.

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

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

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

The description adds meaningful behavioral detail beyond the annotations: it creates a revised brand_ref with the same reference but a new version underneath, like a versioned house_ref. It also scopes behavior by stating there are no accounts or reviewer states yet, which helps set expectations for side effects and workflow position.

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 front-loads the core action and includes only useful qualifications. The versioning comparison and the explicit non-inclusion of approval workflow earn their place because they clarify behavior and boundaries without padding.

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 6-parameter tool with full schema coverage and an output schema, the description provides the missing workflow context: where the inputs come from, what the output represents, and what this stage does not include. Nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds high-level framing by naming selected candidate, locked colours, and suppressed claims, but it doesn't add meaning beyond what the property descriptions already convey; the brand_ref/project_id distinction remains explained only in the schema.

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

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

The description clearly states the tool records a manual brand colour decision: which candidate was chosen, which colours to lock, and which claims to suppress. It ties the action to the sibling brand_guideline_specify tool and distinguishes itself as the decision-recording counterpart, so an agent can tell it apart from brand_guideline_status or brand_guideline_claims.

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

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

The description gives clear context: use this after brand_guideline_specify has produced a candidate, and it notes this is decision-making, not a full approval workflow. It does not explicitly enumerate alternates or when-not-to-use conditions, but the connection to specify and the exclusion of approval states provide solid 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?

Annotation Contradiction: the description states the call creates server-side state — it returns project_id/current_version, creates a second project when continue_project_id is omitted, and leaves generation running server-side — while the annotations declare readOnlyHint=true. An agent trusting the annotation would assume zero side effects. Apart from this conflict, the prose itself is exemplary: it discloses the ~55s async race window, persistent generation that is 'never lost', polling discipline (poll_after_seconds), and 24h brand_ref validity.

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 earns its length: three paragraphs with distinct topics (outputs/follow-ups, versioning, async timing), with the core value proposition front-loaded in the first sentence. Minor redundancy ('keeps running server-side regardless, and is never lost') and slightly convoluted phrasing ('the response's own claim_detail_available_via field') keep 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?

For a tool with 8 params, nested objects, five palette_input modes, an async dual-path, and a multi-tool workflow, the description is nearly complete: outputs, follow-up chain, versioning, and polling are all specified, and an output schema covers return values. Small residual gaps — mode prerequisites (e.g., mode=image requires a prior ingest_image call, mode=archive needs a valid archive name) and failure semantics — prevent a 5.

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

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

The description adds real meaning for continue_project_id by giving concrete continuation examples ('Make it warmer', 'change the secondary', 'render the PDF again'), which is genuinely additive beyond the schema. However, it does not compensate for the roughly 37% of parameters left undocumented in the schema (accessibility_target, tone, language, and object-level descriptions for preferences/identity_assets/output_preferences), so those rely on names and enums alone.

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

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

The opening sentence states a precise verb and resource: 'Generates the case for a brand's colours, not just the colours themselves' — three archive-grounded candidate palettes, scored for distinctiveness, checked for accessibility, and labelled with claim legitimacy. It clearly positions this as the 'case-making' specify step, distinguishing it from obvious siblings like palette_generate, brand_guideline_claims (claim resolution), and brand_guideline_select (recording the choice).

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

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

Explicit sequencing and alternatives are given: follow with brand_guideline_select to record the choice, resolve claim_ids via brand_guideline_claims, and poll via brand_guideline_status with brand_job_ref when the slow path returns processing. The versioning rule states exactly when to pass continue_project_id (refinements, with concrete examples) and when not to ('Start a new project only when the customer asks for a genuinely separate brand').

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 discloses that the call is deterministic and has no LLM cost, which sets cost and behaviour expectations. It also states that the result already carries the rendered palette and download files (PNG, PDF, ASE, JSON, CSS) and instructs the agent to show them to the customer. The guardrail about archive anchors and the palette_finalize handoff add meaningful operational context that annotations do not 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 front-loads the core purpose and output list in the first sentence, then layers cost/determinism, embedded deliverables, presentation instructions, and a cross-tool handoff. Each sentence earns its place: the determinism note, the 'show them to the customer' directive, and the palette_finalize routing all affect agent behavior. It is long but appropriately so for a complex aggregate 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 tool's complexity—5 parameters, output schema, many siblings—the description is operationally complete. It explains what the tool returns, that it is deterministic, that downloads are embedded, how to present results, and what to do if the agent selects its own palette. Parameter details are already in the schema, and return structure is covered by the output schema, so nothing critical is missing.

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

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

The input schema covers all 5 parameters with 100% schema description coverage, so the baseline is 3. The description does not add extra meaning for market, medium, palette, use_case, or brand_category. Since the schema already documents these parameters well, the description does not need to compensate and no deduction is warranted.

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 'Complete brand colour system in one call' and then enumerates concrete deliverables such as colour roles, light/dark role maps, typography guidance, usage rules, design tokens, and citation cards. This gives the agent a specific verb, resource, and scope. It also references palette_finalize as a distinct follow-up, which helps separate this aggregate tool from siblings.

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

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

The description clearly indicates when to use the tool—when a complete brand colour system is needed in one call—and gives an explicit alternative: if the agent chooses its own final palette, it should call palette_finalize once with those colours. It also provides concrete behavioural guidance such as 'Never present the archive anchors... as the colours you are recommending.' It stops short of listing exclusions for narrower palette tasks, but the routing 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?

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 only provide readOnlyHint=true, but the description adds substantial behavioral context: the result already contains the rendered palette and PNG/PDF/ASE/JSON/CSS downloads, the agent must show them, and it must never present archive anchors as recommended colours. This goes well beyond the read-only safety signal and tells the agent what to do with the output.

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?

All four sentences carry distinct, necessary information: what the tool produces, when to use it instead of colour_passport, what the result contains, and the critical finalization/misrepresentation guardrails. No filler or repetition; the key scoping statement is front-loaded.

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

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

Given one well-documented parameter, a readOnlyHint, and the presence of an output schema, the description is complete. It covers selection criteria, expected result contents, customer-facing display behaviour, and the follow-up action to palette_finalize. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% because the single required parameter `hex` already has a clear description and example ('#4A2A50'). The tool description adds no new parameter-level detail beyond calling it a 'single hex colour,' 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 names a specific resource ('single hex colour') and a specific outcome ('Compact semantic fingerprint'), and immediately distinguishes it from colour_passport: 'This is one component of colour_passport.' It is clear which sibling this tool is and is not, without needing to open the schema.

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

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

The description explicitly states when to use this tool: 'use colour_passport for a general colour profile; use this only when the user explicitly wants the fingerprint format alone.' This is a direct usage criterion separating it from the closest sibling. It also gives a downstream rule: call palette_finalize if you choose your own palette from this evidence.

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?

The readOnlyHint annotation covers safety, and the description adds rich behavioral detail: hay_contrast snaps input to Hay's nearest named hue rather than rotating it, returns covered:false for tertiary regions, and the result already carries rendered palettes plus PNG, PDF, ASE, JSON, and CSS downloads. It also discloses a guardrail about never presenting archive anchors as the recommended colours, which is valuable beyond the annotation.

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

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

The description is dense and front-loaded with the core purpose, and every major sentence adds useful information. It is on the longer side, especially the Hay contrast explanation and the customer-facing directives, but those earn their place because they prevent incorrect output presentation.

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 full input schema, output schema, and readOnlyHint annotation, the description is complete enough for an agent to invoke the tool correctly and handle its result. It covers the central output, an important edge case, download availability, and the follow-up palette_finalize behaviour, so no critical guidance is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining the hay_contrast mode in depth, including its distinct snapping behavior and edge-case output. It does not add much specific meaning for hex, but the schema already documents the format with an example.

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: it returns complementary, triadic, analogous, and split-complementary harmonies matched to named archive colours. It then clearly separates the hay_contrast mode from the fixed-angle types, so an agent can tell what this tool uniquely does even among many colour-related siblings.

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

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

The description gives clear context about what the result contains and tells the agent to show rendered palettes to the customer. It also provides a concrete downstream rule: if the agent chooses its own final palette from this evidence, it must call palette_finalize once with those exact colours. It stops short of explicitly naming alternative harmony tools or giving a precise 'use this instead of X' statement.

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

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

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, but the description goes well beyond that: it discloses that edges are returned in separate blocks by relationship_class, that every edge carries an inline 'does_not_mean' caveat, and that empty results are true negatives, not errors. This is exactly the kind of nuanced behavior an agent needs to interpret results correctly.

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 question and densely packed with necessary caveats, examples, and scoping details. Every sentence carries meaning, and the length is justified by the semantic nuance of the relationship graph.

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

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

Given that an output schema exists, the description does not need to explain return formatting. It covers current data population, how to obtain valid record_id values, the meaning of relationship classes, the built-in caveats, and the true-negative semantics, so an agent has enough to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, and the schema already documents include_computed and include_unresolved, including a strong warning about the latter. The description mainly adds contextual advice about sourcing record_id from archive_search or colour_card, but does not add significant meaning beyond the schema.

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

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

The description clearly names a specific operation: one-hop lookup over Colour Memory's stored relationship graph for an archive record. It explains what the tool returns and even separates edge classes, but it never explicitly distinguishes itself from the closely named sibling tool why_connected, so it misses the sibling-differentiation bar for a 5.

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

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

Provides strong context for when to use it: it is scoped to archive record relationships, notes current data population, tells users where to get record_id values, and warns that an empty result is a true negative. It does not explicitly state when not to use it or name alternative tools, so exclusions are missing.

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?

Beyond the readOnlyHint annotation, the description discloses important behaviours: the result carries rendered palette downloads to show the customer, the agent must never present archive anchors as recommendations, and the agent should call palette_finalize if it chooses its own palette. This is rich, actionable behavioural guidance.

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: what is returned, when to use it, how to display results, and a critical warning plus follow-up action. Slightly long but justifiably dense with 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?

For a simple one-parameter read-only tool with an output schema, the description is fully complete. It explains the purpose, the output's practical use, a key pitfall, and the correct downstream action when the agent makes its own palette selection.

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

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

The input schema already provides 100% coverage for the single 'name' parameter. The description reinforces that it must be a 'named archive colour,' which matches the schema example. It adds no major new semantic detail 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 precise verb and resource: 'For any named archive colour, return historical variants, lighter and darker versions with archive matches, and cultural siblings.' This clearly distinguishes the tool's purpose from many colour-related siblings and states exactly what it produces.

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: 'Essential for designers exploring around a colour.' It also provides explicit handoff guidance to palette_finalize when the agent forms its own final palette. It does not name other alternatives or exclusions, but the context is sufficiently 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 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?

The readOnlyHint annotation already signals safety, and the description adds substantial behavioral context beyond that: it is a compound tool that returns rendered palettes with PNG/PDF/ASE/JSON/CSS downloads, it warns against presenting archive anchors as the recommended colours, and it instructs the agent to call palette_finalize for any independently chosen palette. This is rich, non-obvious behavioral disclosure that annotations alone would not 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?

Every sentence earns its place: the compound-tool framing is front-loaded, the replacement chain is explicit, the usage boundary is clear, and the output/presentation warnings are operationally important. Despite its length, there is no filler; each clause carries routing, safety, or workflow information an agent needs.

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 7 parameters and an output schema, the description is complete: it covers what the tool returns, when to use it, when not to, how it differs from siblings, and how to hand off to palette_finalize. The output schema exists, so the absence of a detailed return-value list is not a gap. The readOnlyHint annotation covers the 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 the baseline is 3; the schema already documents concept, medium, avoid, n_colours, and the include_* flags. The description maps some high-level inputs ('concept, medium, ... constraints') to the schema, but it also mentions 'audience,' which is not an actual input parameter. That minor mismatch prevents extra credit beyond the schema-backed baseline.

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

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

The description uses a specific verb+resource framing: 'One-call compound tool' that 'receive[s] a complete design package' from a concept. It explicitly names the sibling tools it replaces, distinguishing it from query_conceptual, palette_from_concept, colour_story, and others, so an agent can immediately tell this is the aggregator tool rather than any individual step.

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 exact use case ('when an AI agent or user needs a complete, deployable colour direction in a single call') and explicitly says what it is not for ('Not for iterative refinement — use individual tools for that'). It also gives follow-up guidance about calling palette_finalize when the agent chooses its own palette, which is actionable and specific.

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

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

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

Given readOnlyHint is already present, the description adds substantial behavioral context: each answer names its source, locator, and what the evidence CANNOT support; responses explicitly avoid averaging incompatible metric types; and output is evidence-led rather than a summary. This goes well beyond the annotation and materially helps an agent predict 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 dense but every sentence earns its place: core purpose first, then source list, then example questions, then the critical non-interchangeability caveat. The longer source enumeration is justified by the tool's broad historical scope. It remains well-structured and front-loaded.

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

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

The tool is complex with five parameters and seven distinct source types, but the description covers the essential gaps: which sources exist, how to frame queries, what the response includes, and a key behavioral constraint. With rich schema and output schema already present, nothing critical is missing for an agent deciding whether and how to invoke 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?

The input schema already covers all five parameters with descriptions, so the baseline is 3. The description adds contextual color about the seven valid sources and the plain-English nature of queries, but it does not explain per-parameter formats or constraints beyond the schema. It is adequate but not necessary for parameter understanding.

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

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

The description opens with a specific action: 'Ask a question about how historical colour authorities actually reasoned, and get evidence with provenance rather than a summary.' It names the resource (seven historical sources) and the distinctive output type, which clearly separates it from colour/palette or archive siblings. The scope and intent are unmistakable.

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

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

It provides concrete use cases: 'how do I paint a leaf', 'what did Bradley's disc proportions measure', and checking claims attributed to the named authors. It also warns that the source numbers are NOT interchangeable and that the tool will not average them. It does not explicitly name sibling alternatives or state when not to use this tool, so it falls just 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 description discloses substantial behavioral nuance far beyond the readOnlyHint annotation: how grouping is determined, what grouping_basis and provenance_credit report, that room/surface assignment is editorial, that orientation does not affect palette selection, that the full response is large, and that the response already carries downloadable artifacts. It also warns agents never to present derivation anchors as recommended colours.

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

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

The description is long, but nearly every sentence adds decision-relevant behavior or workflow guidance for a complex tool. It is front-loaded with the core purpose and example, then organized around grouping, outputs, and cross-tool handoffs, making the length justifiable despite some density.

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

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

For a complex tool with no output schema, the description fully covers what the agent needs: input shape, grouping semantics, evidence disclosure, output artifacts, size concerns, and sibling-tool handoffs. It also explains how to pass house_ref to palette_pdf and when to call palette_finalize, leaving little ambiguity about how to invoke and use the result.

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 detailed descriptions for most parameters, including concept, archive, rooms, orientation, minimum_claim_strength, and strict_semantic_colour. The tool description adds little parameter-specific meaning beyond an example and the requirement that a single archive supply all room colours, so the schema carries the bulk of 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: 'Generate a complete multi-room house colour scheme from a single archive.' It clearly distinguishes itself from sibling tools, especially interior_specify, and includes a concrete example of the expected input shape.

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 interior_specify instead for a single room without cross-room grouping,' giving a clear exclusion condition. It also provides downstream routing guidance for palette_finalize and palette_pdf, so an agent knows exactly when and how to chain follow-up tool calls.

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