Colour Memory

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

Annotation readOnlyHint:true already establishes this is a safe read operation. Description adds that it only evaluates a single pair (scope limitation) and hints at the tool's relationship to accessibility_matrix. No additional side effects or context are disclosed, but given the annotation and simple tool, this is adequate.

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

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

Two sentences, no filler. The first sentence states the primary function, the second sentence gives alternative guidance. Extremely 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?

Tool is simple, has a readOnly annotation, an output schema, and complete parameter schema. The description covers the tool's purpose and alternative usage. The only missing info (e.g., WCAG version or return format) is likely covered by the output schema and title.

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% as both hex_val and background have descriptions in the input schema. Description adds no additional parameter details beyond what schema already provides. Baseline 3 is appropriate.

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

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

Description uses specific verb 'Evaluates' and identifies exact scope: 'contrast for a single foreground/background pair'. It also distinguishes from sibling accessibility_matrix by contrasting single pair vs palettes/multiple colours.

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

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

Explicitly states when NOT to use: 'For palettes or multiple colours, use accessibility_matrix instead', and explains benefit: 'it replaces multiple accessibility_check calls in one response'. This is clear alternative guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds output details (ranking, WCAG grades, recommendations) but no additional behavioral caveats such as auth requirements or side effects, and it does not contradict 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 well-structured sentence with no filler. Each clause contributes the input, the action, and the output format.

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 only two well-described parameters, a readOnly annotation, and an output schema, the description fully covers tool invocation. It clearly states what the tool accepts and what it returns, leaving no ambiguity for an agent.

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

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

Schema descriptions cover 100% of the two parameters, so the baseline is 3. The description restates background and palette as hex values but adds no new parameter-level semantics 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 opens with 'Given a background hex and a palette of candidate foreground colours, return them ranked by contrast ratio' – a clear verb, resource, and output. The WCAG grades and text-type recommendations distinguish it from broader siblings like accessibility_check or colour_compare.

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

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

The 'Given a background hex and a palette' phrasing establishes a concrete use case: selecting accessible foreground colors for body, large, and UI text. It does not name alternatives or exclusions, so it stops short of the most explicit 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 signals a safe read operation, and the description adds valuable output behavior: what combinations are computed, which contrast grades (AA/AAA normal/large) are included, and that a summary is returned. It does not cover edge cases like invalid hex values, but the schema provides type/format coverage, so the marginal disclosure 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?

Two concise sentences: the first states the action and output, the second captures the key usage decision. Every word contributes without redundancy, making it easy to parse for an agent.

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

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

Given the tool has one parameter, a 100% schema-covered parameter description, an output schema, and read-only annotations, the description provides all necessary context: what it computes, the output structure, and when to choose it. It is fully adequate for an agent to invoke correctly.

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

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

The schema description covers the parameter fully (array of hex values with an example), so the baseline is 3 even without extra detail in the description. The description only says 'palette array,' adding no new semantics beyond the schema, so no increase.

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 ('Accept a palette array and return every foreground/background combination') and clearly distinguishes itself from the sibling tool accessibility_check by stating it computes a full matrix rather than single checks. This is a concrete verb+resource pairing with clear 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 tells the agent when to use this tool: 'Use this instead of calling accessibility_check multiple times for a palette.' This names the alternative and gives a reason (avoiding multiple calls), which is strong guidance for tool selection.

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

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

The description adds meaningful behavioral context beyond the readOnlyHint annotation: it is deterministic, has no LLM cost, and returns a predefined set of rule categories. This helps the agent anticipate the tool's performance and output, though it does not discuss edge cases or failure modes. 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, front-loaded with the primary action and output list. The final note 'Deterministic, no LLM cost' is concise and provides useful selection information without padding. Every word earns its place.

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

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

Given the tool's simple input (one array) and the presence of an output schema, the description sufficiently covers the purpose and behavior, including output categories. It lacks an example or clarification of the 'WCAG matrix' phrasing, but the combination of schema and description is reasonably complete for an agent to 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 input schema already fully describes the only parameter ('palette' as an array of hex values) with 100% coverage. The description adds little beyond the ambiguous phrase 'palette WCAG matrix', which might confuse the input format. Since the schema carries the parameter meaning, 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 with a specific verb ('Convert') and resource ('a palette WCAG matrix'), and enumerates the distinct output types (safe pairs, AA-only pairs, etc.). This distinguishes it from sibling tools like accessibility_matrix, which likely produces the matrix rather than the rules.

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 palette and need actionable design-system rules. It also adds a decision factor with 'Deterministic, no LLM cost', suggesting it is a reliable and low-cost option. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a full when/when-not guide.

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 'Return simulated hex values', so there is no contradiction. The description adds behavioral context by naming the Brettel-Vienot-Mollon model and specifying the three simulated types, providing more insight than the annotation alone.

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

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

The description is a single, front-loaded sentence that conveys the action, the specific output, and the method. No fluff or repetition, every word earns its place.

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

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

Given the tool's low complexity (one parameter, output schema provided), the description is complete. It explains what it returns, the model used, and the three color blindness types. No critical context 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% for the single parameter 'hex_val', so the baseline is 3. The description does not add additional parameter semantics beyond what the schema already provides, but it doesn't need to.

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 verb ('Return') and a specific resource (simulated hex values for three types of color blindness), using a named model. It distinguishes itself from sibling tools by focusing on simulation output rather than checking or comparing accessibility features.

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

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

The description implies usage for simulating color blindness hex values but does not explicitly state when to use it over alternative tools like accessibility_check or colour_compare. There is no mention of exclusions or alternative tools, so the guidance is merely implied.

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

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

The description goes far beyond the readOnlyHint annotation, detailing evidence-filtering rules (exclusion of reject/stub/blank-source entries), the honest incomplete-result behavior (ok:false, error_code), the application of negative constraints at retrieval time, and special handling for locked_palette. This gives the agent a strong behavioral model.

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

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

The description is longer than minimal, but every sentence carries distinct information: purpose, deliverable components, supported models, example, use case, filtering rules, failure handling, negative constraints, and locked_palette behavior. It is well-structured and front-loaded, though some sentences paraphrase schema notes slightly.

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 (10 params, multiple filtering behaviors, locked_palette mode, failure modes), the description is remarkably complete. It covers retrieval rules, evidence quality floors, negative constraints, special-case behavior, and model support. The presence of an output schema means return-value documentation is unnecessary, so no additional info 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?

Although the schema already describes all 10 parameters at 100% coverage, the description adds significant cross-parameter semantics: how 'avoid' and negation phrases in 'concept' affect retrieval, how 'locked_palette' bypasses evidence filtering, how 'minimum_claim_strength' interacts with 'claim_role', and how palette_size relates to the honest failure mode. This goes beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'Generate a complete colour direction package for another AI agent or image generation model.' It clearly distinguishes itself from siblings like palette_generate or image_brief by specifying the cross-AI delivery format, including agent brief, tokens, prompt, negative prompt, and lighting notes.

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 a clear use case ('Use this to make Colour Memory the colour layer for other AI systems') and an explicit example ('task='luxury hotel bedroom', concept='Ottoman winter luxury', model='midjourney''). However, it does not name alternatives or explicitly say when not to use this tool, 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 provide readOnlyHint=true; description does not contradict. Adds behavioral context by detailing output (fidelity score 0-100, dE2000 distance, match quality, verdict) and input flexibility (URL or base64), going beyond the bare annotation.

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

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

Two sentences, each earning its place: first states purpose, second covers usage, inputs, outputs, and workflow position. Front-loaded and free of redundant phrasing.

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

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

Output schema exists, so return values need no description. The description covers when to use it, what inputs to supply, what it returns, and where it fits in the agent_brief→image generation workflow. Complete for a read-only verification 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 has 100% coverage with descriptions for all three parameters. Description reinforces that target_palette comes from agent_brief colour_tokens, but adds no syntax or format details beyond what the schema already provides.

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

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

Specific verb 'Verify' + resource 'AI-generated image' + scope 'colours specified in an agent_brief call'. Clearly distinguishes from siblings like colour_compare or palette_verdict by referencing agent_brief and the fidelity scoring workflow.

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

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

Explicitly states 'Use after agent_brief + image generation to close the colour loop' – gives clear situational context. Does not name alternatives or exclusions, but the workflow context is unambiguous.

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

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

With readOnlyHint=true, the annotation provides the safety profile. The description adds process context: the archive finds the contradiction and Claude writes the outputs, including the specific output types (one-liner, short story, tweet) and an example. No destructive or side-effect behavior is relevant, so the description goes beyond the annotation.

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

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

The description is two sentences plus an illustrative example. It front-loads the core purpose, then gives instructions and use cases. Every sentence earns its place with no redundancy, making it 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?

Given the tool's moderate complexity, the description covers purpose, usage, parameters, example output, and target use cases. The presence of an output schema handles return values, so the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces parameter roles with examples (e.g., 'love' + 'red' returns dark green), but it doesn't add much beyond the schema's own descriptions. It clarifies the interaction between concept and expected_colour, earning a moderate score.

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

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

The description clearly states a specific verb+resource: 'Find the most surprising archive colour for a concept and generate a memorable one-liner subverting the obvious expectation.' It also provides concrete outputs (one-liner, short story, tweet) and an example, which distinguishes 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?

The description gives explicit use cases: 'Use this for public-facing demos, content, and brand storytelling.' It does not list alternatives or exclusion criteria, but the context is clear enough for an agent to choose this tool over others.

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 establishes a safe read operation, and the description does not contradict it. The description adds some behavioral context about preventing reports that ignore evidence gaps, but it mostly reiterates the output structure (coverage matrix, source type) rather than disclosing side effects, permissions, or limitations.

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

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

The description is three sentences, front-loaded with the core action, followed by output details and a practical usage tip. Every sentence earns its place with no redundant or promotional language.

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 format, and workflow timing concisely, while the annotation and complete schema handle safety and parameters. It lacks only an explicit contrast with the similar sibling archive_evidence_gap, but that is not essential for using 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?

The input schema has 100% coverage with clear descriptions for both 'themes' and 'archives', including examples. The description only restates 'a list of themes' and does not add 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 uses a specific verb ('report') with a clear resource ('coverage gap in the archive') and details the output (coverage matrix, grades, claim strength). It differentiates itself from sibling tools by focusing on per-theme evidence coverage and explicitly referencing downstream tools like archive_report_brief and brief_forensic.

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

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

The description explicitly states when to use the tool: 'Use this BEFORE building an archive_report_brief or brief_forensic'. This provides a clear workflow context, though it does not mention when not to use it or compare it directly with alternative tools.

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

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

With readOnlyHint=true, the description appropriately adds detail beyond the annotation: the specific checks (date range, known modern archives) and the return fields (risk, relevance, safe/unsafe phrasing). The concrete example illustrates typical behavior, though it does not disclose edge cases or limitations.

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

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

Three sentences, front-loaded with the primary purpose, followed by the detection logic and output summary. Every sentence contributes meaning, 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?

The tool has an output schema and readOnlyHint annotation. The description further explains the output values (anachronism_risk, period_relevance, safe_phrasing, unsafe_phrasing) and the practical scenario, making it sufficiently complete for an AI agent to understand when 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?

Schema description coverage is 100% for top-level parameters, so the baseline is 3. The description mentions 'primary source date' and 'archive', which maps to entry fields, but it does not add meaningful semantic detail beyond the schema's own descriptions (e.g., 'Start year e.g. 1714').

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 ('Check a list of colour entries') and names the exact function (anachronism risk). The concrete example of a 2011 racing silk being presented as Georgian evidence clearly distinguishes this from sibling tools like archive_provenance or colour_cultural_risk.

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

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

The phrase 'Essential for historical documents' provides clear contextual guidance on when to use the tool. It does not explicitly mention alternatives or exclusions, but the focus on anachronism detection and the illustrative scenario make the intended use obvious.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context: it 'turns the absence of evidence into a forensic finding rather than a gap to fill with invention' and mentions the output includes 'safe wording for the agent to use.' 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 primary action and outcome, then provides a concrete example and use cases. Every sentence earns its place; it is detailed but not bloated.

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 does not need to enumerate return fields, but it does anyway in the example. Combined with the annotations, schema descriptions for all 4 parameters, and clear workflow contexts, this description is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a concrete example (![hex] #4A535C + 'cyanosis in a death chamber') and explains what each major parameter contributes (hex and proposed_claim) and the nature of the response. This is more than the schema provides alone.

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

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

The description uses a specific verb-resource pairing: 'Given a hex value and a proposed claim about it, return whether the archive supports that claim...' This clearly distinguishes it from siblings like archive_search, archive_coverage_gap, and colour_forensics by framing it as an anti-hallucination endpoint that produces 'safe agent wording.'

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 states when to use: 'Essential for museum, documentary, editorial, legal, and forensic workflows.' It does not mention when not to use it or explicitly name alternatives, but the context and example make the intended use clear.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds meaningful behavioral context by describing the type of output (provenance categories, confidence, citation format) and that it is a research tool, going beyond the annotation.

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

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

The description is two sentences, front-loaded with the core purpose and immediately followed by usage differentiation. No filler or redundancy.

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

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

With an output schema present and clear usage guidance, the description covers purpose, sibling differentiation, and output characteristics. It is complete for a read-only research tool of this complexity.

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

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

Schema description coverage is 100% for the single parameter, which includes examples like 'Love Idleness'. The description does not add param-specific semantics, but the schema fully handles them, 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 a specific verb ('Explains'), a specific resource ('provenance of a named archive colour'), and distinct output elements (documented fact vs computational derivation vs cultural interpretation, confidence, citation format). It also differentiates itself from the sibling tool colour_passport by noting it is a component but also a standalone 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 directs usage: 'Use colour_passport for a general profile; call this directly for research workflows needing full source-chain detail.' This provides clear when-to-use guidance and names the alternative 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?

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context beyond that: 'Two Claude calls total' (resource usage), hard period gates, strict evidence floors ('Never silently relaxed'), and error handling for insufficient results (INSUFFICIENT_PALETTE_RESULTS). It contradicts nothing in 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 a single dense paragraph that front-loads the core value proposition. It is fairly long, but each sentence adds necessary context (output list, usage priority, alternatives). The output list may duplicate what the output schema already conveys, slightly bloating the text, but it remains well-structured.

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

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

Given the tool's complexity (16 parameters, output schema, minimal annotations), the description provides a complete high-level orientation: purpose, expected outputs, usage guidance, and alternatives. Detailed parameter behavior is left to the exhaustive schema, so there are no critical gaps for an agent to select and call the tool effectively.

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

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

Schema description coverage is 100% with detailed per-parameter descriptions. The tool description only paraphrases a subset of parameters (title, audience, themes, archives, avoid, n_colours) without adding new semantics or format details beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description opens with a specific, action-oriented claim: 'One-call complete archive research package for a document, PDF, or editorial brief.' It clearly differentiates from siblings by explicitly stating it replaces chaining archive_search + get_colour_card + cliche_breaker + agent_brief, making the tool's unique value 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 gives explicit when-to-use instruction: 'Use this first for any document workflow.' It also names the alternatives it replaces, providing clear guidance on when this tool should be selected over the pointed-to sibling tools.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: the result_path values ('direct', 'broadened', 'redirected'), the guarantee that it 'Never returns a bare empty result,' and the entity_mode exact-exclusion behavior. This significantly enriches the agent's understanding of how the tool behaves.

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

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

The description is relatively long but well-structured, opening with the core purpose, then differentiating from siblings, providing illustrative examples, and explaining edge-case behavior. Each sentence contributes useful information, though the example match counts (e.g., '28 matches') are optional. The structure is front-loaded and readable.

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, so return values are covered. The description provides a complete operational picture: search scope, differentiation from conceptual search, result_path fallback behavior, entity_mode semantics, and the include_full snippet option. With an output schema and rich sibling context, this description is thorough.

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 8 parameters with descriptions (100% coverage), so the baseline is 3. The description adds semantic value by explaining entity_mode with a detailed example ('Rose' vs 'Rose Pink') and clarifying the meaning of result_path, which helps select correct parameter values. This 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+resource: 'Full-text keyword search across all archive colour names and notes.' It clearly distinguishes itself from conceptual embedding search by stating it 'Complements conceptual embedding search with exact keyword matching' and provides concrete examples of queries and result counts, making the tool's purpose unambiguous.

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

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

The description explicitly tells when to use this tool over alternatives by contrasting it with 'conceptual embedding search' and explaining the entity_mode switch for botanical identity vs. text. It gives a clear decision framework: use 'exact' when meaning the plant, not the word. This is strong 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?

Annotations already provide readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral details: 'Deterministic. No LLM cost.' and enumerates the output types, providing context 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 states the purpose, the second enumerates deliverables, and the third adds a key behavioral note. Every sentence adds value with no filler.

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

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

Given the output schema exists, the description need not detail return formatting. It provides a clear deliverable list and behavioral notes. However, it could clarify how parameters influence the pack (e.g., market or medium variants), which would make it more complete for a complex 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 all five parameters. The description does not add parameter-specific semantics beyond listing the outputs, which may implicitly depend on parameters like 'medium' or 'market', but this is not stated. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: 'Complete brand asset pack' and lists the specific returned artifacts (CSS variables, Tailwind config, Figma tokens JSON, citation cards, Markdown brand guide). This clearly differentiates it from more specialized siblings like palette_export or palette_pdf.

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

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

The phrase 'Everything a brand team needs to ship' implies this is the all-in-one export tool, but it does not explicitly name alternatives or state when not to use it. There are many sibling export tools, and the description offers no direct comparison or exclusion criteria.

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

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

The description adds crucial behavioral context beyond the readOnlyHint annotation: it is synchronous, uses no model call, and previously made a hidden LLM call. It discloses the exact output keys, the 'not_computed' status, and the continuation mechanism, which is far more transparent than the annotation alone.

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

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

The description is longer than average but every sentence earns its place by explaining scope, performance implications, hidden behavior, and follow-up instructions. It is front-loaded with the main purpose and deterministic nature, though the final 'Replaces...' sentence could be tightened.

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

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

Given the tool's complexity and the presence of an output schema, the description is remarkably complete: it explains what is computed, what is deferred, how to continue the workflow, and how it relates to sibling tools. The agent can confidently decide whether to call this tool and what to do with 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 has 100% description coverage for all five parameters, so the baseline is appropriate. The description lists the parameters but does not add new semantic detail beyond the schema; it only contextualizes their role within the audit computation.

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

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

The description states a specific verb and resource: 'brand colour audit' with a clear deterministic scope. It distinguishes itself from siblings by explicitly explaining that it replaces chaining accessibility_matrix + cultural_risk_assessment and defers interpretation to palette_verdict.

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

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

It explicitly says what is computed and what is NOT computed, and instructs the agent to forward continuation arguments to the palette_verdict tool. It also names the alternative (palette_verdict) and clarifies that interpretation is a separate, optional second call rather than hidden.

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 annotations include readOnlyHint=true, establishing a safe read-only operation. The description adds valuable behavioral detail beyond that: it names the specific algorithm (CIEDE2000), the output components (distinctiveness score, ownership verdict, plain-English summary, strategic recommendation), and the verdict value set. This gives the agent a clear picture of what to expect without contradicting 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 compact yet information-dense: a leading question, a short input list, a structured output list, and a usage sentence. Every sentence earns its place and the text is front-loaded with the tool's purpose. It is appropriately sized for a tool with this many inputs and outputs.

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 (so return values are already structurally specified) and annotations declare readOnlyHint, the description covers the remaining context: what the tool does, when to use it, what inputs are expected, and what kind of output to anticipate. No critical contextual gap is apparent for selection and invocation.

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

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

Schema description coverage is 100%, so the schema already explains all six parameters. The description simply enumerates the parameter categories ('brand hex, brand name, competitor hexes and names, market, region') without adding new syntactic or semantic detail beyond the schema. The baseline of 3 is appropriate since the description does not deepens 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 the core question—'Can this brand own this colour against these competitors in this market?'—and clearly lists the inputs and outputs, including CIEDE2000 distance, verdict, and recommendation. It distinguishes itself from sibling tools by framing the purpose as brand ownership in a competitive market and explicitly stating it replaces manual colour distance checks and competitor palette 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 before committing to a brand colour in a competitive market' and notes it replaces manual colour distance checks and competitor palette analysis. However, it does not explicitly mention when not to use it or alternative sibling tools, so it stops 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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds value by explaining it reads a 'frozen brand_ref snapshot' and 'never re-runs generation or mutates anything,' plus the behavior of omitting claim_ids. This goes beyond the annotation hints.

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 primary action, each sentence earning its place. It's concise but information-dense, with no filler.

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

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

With an output schema present and full parameter coverage, the description doesn't need return-value detail. It covers behavioral guarantees, input constraints, and sibling relationships, making it 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying that claim_ids are 'returned inline on every colour' by sibling tools, and that brand_ref/project_id are mutually exclusive ('exactly one'). This is useful context beyond the schema definitions.

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

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

The description opens with a specific verb and resource: 'Resolves claim_id values ... into their full claim record.' It clearly lists what the record contains and references sibling tools (brand_guideline_specify/select) that produce the claim_ids, distinguishing it from related tools.

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

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

The description provides clear context: use with claim_ids from brand_guideline_specify/select, omit to get all claims, and accept brand_ref or project_id exactly one, same as brand_guideline_pdf. It doesn't explicitly state when not to use it, but the guidance is sufficiently 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 already mark the tool as read-only and idempotent, but the description adds crucial behavioral detail: variable page count, omission of empty sections, provisional preview labeling, and the guarantee never to mutate or recompute. This goes far beyond the structured annotations and enriches the agent's understanding.

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 contributes a substantive detail about output composition or behavioral guardrails. It is longer than average but contains no filler or repeated information, earning a strong score despite its 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?

With rich annotations, an output schema, and a description that covers output content, variable behavior, input prerequisites, and safety guarantees, the tool is fully specified. An agent has all necessary information to decide when to use it and what to expect.

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 per-parameter descriptions, so the baseline is 3. The description adds the essential exclusivity rule ('exactly one of brand_ref or project_id') and traces brand_ref provenance to brand_guideline_specify/select, providing context not captured 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 opens with a specific verb ('Renders') and resource ('client-facing brand colour standard PDF') derived from an existing brand_ref. It clearly differentiates from sibling tools like brand_guideline_specify and brand_guideline_select by focusing on rendering an existing snapshot rather than creating or selecting.

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 prerequisite ('from an existing brand_ref'), gives the exclusivity constraint ('Accepts exactly one of brand_ref or project_id'), and explicitly names what it never does ('never re-runs brand_guideline_specify, never rematches an archive'). It stops short of naming alternative tools for those scenarios, but the guidance is clear and actionable.

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

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

With annotations already covering readOnly=false and destructive=false, the description adds behavioral context: it produces a new version under the same reference (exactly like a versioned house_ref), suppresses claims, and locks colours. It also clarifies the tool's scope (decision-making only, not approval). This goes beyond the annotations without contradicting them.

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 and every clause carries meaning: the action, the inputs, the output, and the scope limitation. It is front-loaded with the main verb and avoids redundancy or filler, achieving high information density in minimal 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 tool has an output schema (so return values are covered) and the description covers the full workflow context: the source of brand_ref, the analogy to house_ref, and the limitation to decision-making. It does not explicitly describe the output structure or prerequisites like authentication, but those are either inferred or handled by the schema, making this largely 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% for all 5 parameters, so the baseline is 3. The description adds meaning by explaining that locked_colour_ids are 'for future iteration' and suppressed_claim_ids are 'marked superseded,' and by relating selected_candidate_id to brand_guideline_specify. This extra context is helpful but not essential given the schema's own 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 ('Records') and clearly identifies the resource: the chosen brand_guideline_specify candidate, locked colours, and suppressed claims. It distinguishes the tool from its sibling brand_guideline_specify by stating it records the decision and produces a revised version, and it explicitly sets scope boundaries ('not a full approval workflow').

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

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

The description implies the tool is used after brand_guideline_specify (the candidate source) and explains the outcome via the house_ref analogy. It also states when not to use it ('No accounts or reviewer states yet'), but it does not explicitly name alternative tools for approval workflows or provide a direct when-to-use versus sibling comparison.

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 significant behavioral traits beyond the annotations: the async race (55s window), the processing status response, the 'generation keeps running server-side regardless, and is never lost' guarantee, and the poll_after_seconds guidance. It also clarifies claim labelling semantics. This is exceptional transparency.

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

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

Although the description is long, it is well-structured and front-loaded: the first sentence states the core purpose, followed by output details, next steps, and timing. Every sentence adds unique value (e.g., valid 24h, claim_id, async behavior), 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?

The description is exceptionally complete for a tool with 7 parameters, nested objects, an output schema, and many siblings. It covers the purpose, the exact process, the asynchronous failure mode, the return contract, and next-step tools. The presence of an output schema means it need not detail every return field, but it still explains key ones like brand_ref and claim_id.

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 itself does not explain input parameters, but the schema provides meaningful descriptions for most fields (e.g., constraints, preferences, palette_input). Schema coverage is 57%, which is moderate; the description adds no parameter-specific meaning beyond the schema, so 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 the tool's verb and resource: 'Generates the case for a brand's colours, not just the colours themselves' and describes producing 'three genuinely different, archive-grounded candidate palettes'. It distinguishes from siblings by emphasizing the 'case' aspect and explicitly naming follow-up tools like brand_guideline_claims and brand_guideline_select.

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

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

The description gives explicit when-to-use guidance and alternatives: it instructs to 'Follow with brand_guideline_select to record which candidate was chosen', 'resolve those into full source/permitted-claim/do_not_say text with brand_guideline_claims', and 'Call brand_guideline_status with that brand_job_ref to retrieve the completed result'. It also mentions the polling guidance. This is a clear usage guide.

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 read-only, idempotent, non-destructive. Description adds behavioral context: it's an in-process lookup, never re-runs generation, and details all possible return states including error handling (BRAND_JOB_NOT_FOUND). This goes beyond the annotations and gives full transparency.

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

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

The description is a single dense paragraph but every clause adds value: purpose, conditions, read-only nature, return shapes, error behavior, and pointers to related tools. It is front-loaded and free of filler.

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

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

The description fully covers all possible outcomes (processing, complete, failed, not found) and how to proceed with the returned brand_ref. It references the output schema implicitly and the sibling tool family, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with a clear parameter description. The tool description adds semantic context by explaining the parameter's origin ('returned by brand_guideline_specify') and its role in a race-to-complete scenario, which is not 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 resolves a brand_job_ref from brand_guideline_specify when its race-to-complete window elapsed. It uses a specific verb ('Resolves') and resource ('brand_job_ref'), and distinguishes itself from siblings by focusing on status retrieval, not generation or full detail retrieval.

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 it: when brand_guideline_specify's race-to-complete window elapsed before generation finished. It also provides guidance on alternatives by directing the user to use brand_guideline_select/brand_guideline_pdf/brand_guideline_claims for full detail, and clarifies it never re-runs generation.

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 this is a one-call aggregated report producing a single complete response. The 'Two Claude calls total' phrase is slightly ambiguous, but it is not contradictory with the read-only hint and adds context about the tool's internal workflow.

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 primary purpose. It lists inputs, outputs, and alternatives efficiently. The 'Two Claude calls total' phrase is redundant and slightly confusing, which prevents a perfect score, but overall every sentence earns its place.

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

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

Given the 100% schema coverage, nested object schema, and output schema, the description provides sufficient context. It tells the agent what inputs are needed, what outputs to expect, and when to use it instead of chaining alternatives. This is complete for a complex aggregator 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% and each parameter has a clear description (e.g., hex, markets, product_type). The description restates the main input categories but does not add semantic details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool produces a 'complete brand colour intelligence report' and enumerates specific outputs. It distinguishes itself from siblings by saying 'Use this instead of chaining colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief separately.', making the resource and action 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?

Explicit guidance is provided: 'Use this instead of chaining colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief separately.' This tells the agent exactly when to choose this tool over alternatives and that it is a consolidated one-call option.

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

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

With readOnlyHint=true, the annotation already signals safety, but the description adds valuable behavioral traits: 'Deterministic. No LLM cost.' and enumerates all output categories. This goes beyond the annotation and gives the agent confidence about predictability and cost.

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 tight sentences: the first summarizes the tool's value, the second lists deliverables. 'Deterministic' and 'No LLM cost' are important operational details, and no word is wasted. Front-loaded and 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 covers the tool's purpose, outputs, and operational traits. Since an output schema exists, return values are structurally defined, and the description still lists them for clarity. It is complete for a read-only aggregation 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 all parameters. The description adds no parameter-specific guidance; it focuses on outputs rather than inputs. This matches the baseline 3 for high schema coverage.

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

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

The description states exactly what the tool does: 'Complete brand colour system in one call' and lists all returned components (colour roles, dark/light maps, typography, usage rules, design tokens, citation cards). This clearly distinguishes it from sibling tools that focus on individual aspects (e.g., palette_light_dark, colour_card).

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

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

The phrase 'in one call' and 'complete' imply this is for holistic brand colour needs, giving clear context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of the top score.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds value by enumerating the return categories (hex, archive, provenance, cultural notes). It does not disclose potential ambiguity with colour names or fallback behavior between name and slug, but with the annotation baseline this is adequate.

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

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

One front-loaded sentence that immediately states the action and the key output items. Every word earns its place; there is 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?

This is a simple lookup tool with a read-only annotation and an output schema present, so the description does not need to explain return values. It covers the primary purpose and outputs. The only gap is lack of guidance on when to use which parameter or how to handle no parameters, but given the tool's simplicity and schema support, the description is sufficiently complete.

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

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

Schema description coverage is 100%: both 'name' and 'slug' have descriptive help text, and slug explicitly says it is preferred over name for reliable retrieval. The description adds little beyond 'named colour' and the output list; it does not provide syntax or format details not already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('look up') and a resource ('named colour'), then lists the exact outputs: hex, archive, provenance, and cultural notes. This distinguishes it from sibling tools like colour_dna or colour_passport by scoping the return content.

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

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

No guidance is given on when to use this tool versus the many sibling colour_* tools. The description implies 'look up a named colour' but does not mention alternatives, exclusions, or the schema's note that slug is preferred over name. There is no explicit 'use when' or 'prefer X over Y' guidance.

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

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

Annotations declare readOnlyHint=true, so the tool is understood to be a read operation. The description adds that it returns harmony type, clash warnings, contrast summary, and deployment rules, but does not disclose additional behavioural details such as error handling or parsing behavior. This is acceptable given the read-only annotation and modest complexity.

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 efficiently states the input scope and output highlights. It is front-loaded with the core action and remains informative without excessive detail.

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

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

With a full input schema, output schema, and read-only annotation, the description covers the essential scope and purpose. It mentions the contexts and return categories, making it sufficiently complete for an agent to 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 fully describes both parameters: 'colours' as 2-5 hex values and 'context' with allowed values. The description does not add new parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states the tool 'Assess 2-5 colours as a combination for a given context' and enumerates return types (harmony type, clash warnings, contrast summary, deployment rules). This clearly identifies the action, resource, and output, distinguishing it from sibling colour tools like colour_compare or colour_harmonies.

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

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

The description provides clear context on when to use the tool: when you have 2-5 colours and need to assess their combination for a specific context (UI, data viz, fashion, etc.). However, it does not explicitly mention alternatives or when not to use it, though the specificity implicitly guides selection.

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

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

The readOnlyHint annotation already establishes safety, and the description adds no contradicting information. The description does add contextual value by detailing the nature of the returned analysis (perceptual, semantic, cultural), but it does not disclose additional behavioral traits beyond what the annotation provides, such as rate limits or side effects.

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 focused sentences with no redundant content. It front-loads the core purpose, then efficiently covers outputs, use cases, and exclusions. The 'Not a harmony tool' note earns its place by preventing category confusion.

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

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

For a simple two-parameter, read-only tool with no output schema, this description provides all essential context: what it does, what it returns, when to use it, and how it differs from harmony tools. The level of detail is appropriate for the tool's complexity.

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

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

Schema coverage is 100%, with clear descriptions and examples for hex_a and hex_b. The description merely says 'any two hex values' and does not add extra semantics, constraints, or format details beyond the schema, so it neither enhances nor detracts from the schema's clarity.

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 ('deep perceptual and semantic comparison') and resource ('any two hex values'), then enumerates the quantified outputs (LRV, chroma, hue angle, warmth, CIEDE2000 distance). It also distinguishes itself from sibling tools by explicitly noting 'Not a harmony tool — this is a decision and reasoning 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?

It explicitly tells the agent when to use the tool: 'Use when choosing between two colours or explaining why one works better than another.' It also provides a clear exclusion: 'Not a harmony tool,' which prevents misuse and helps differentiate from 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=true annotation already indicating a safe read operation, the description adds meaningful context by detailing the types of cultural risk covered (symbolic weight, regional taboos, religious associations, market flags). It also clarifies that the tool is a component of colour_passport, giving structural insight. No contradictions 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 concise and front-loaded: the first sentence states the core purpose, while the second provides usage differentiation. No filler words, and every sentence serves a distinct purpose – ideal for efficient parsing.

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

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

Given the tool's moderate complexity (3 optional parameters, an output schema present), the description fully covers its purpose, scope, and relationship to sibling tools. Since an output schema exists, return-value details are unnecessary. The description is complete for an agent to select and invoke this tool confidently.

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 provides 100% parameter coverage with descriptions for hex, markets, and palette. The description mentions 'hex value or palette' which mirrors the parameters but does not add new semantic meaning beyond what the schema already conveys. Thus, the schema carries the burden, earning the baseline score.

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

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

The description clearly states the tool's purpose: 'Cultural risk assessment for a hex value or palette' and lists specific aspects (symbolic weight, regional taboos, religious associations, market flags). It also distinguishes itself from colour_passport, explicitly positioning this tool as a focused risk check for palettes or when cultural risk is the only concern.

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 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 the alternative, specifies when to use it, and implies when not to use it (i.e., when a general profile is needed).

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

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

readOnlyHint=true already covers safety, and the description adds that this is a compact semantic fingerprint and a component of colour_passport. However, it doesn't describe output details or any behavioral nuances beyond what annotations and the output schema already imply. No contradiction.

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

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

Two sentences with no fluff. The first sentence states the core purpose; the second gives usage guidance. Information is front-loaded and every word earns its place.

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

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

For a simple read-only tool with a single parameter and an output schema, the description fully covers purpose, usage, and differentiation from the closely related colour_passport. No gaps.

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

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

Schema description coverage is 100% (hex is described with format and example). The description's 'single hex colour' reinforces the param but adds no new meaning beyond the schema, 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 opens with 'Compact semantic fingerprint for a single hex colour,' using a specific verb (fingerprint) and resource (single hex colour). It further distinguishes from siblings by explicitly noting it is a component of 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?

Provides explicit when-to-use guidance: 'Use colour_passport for a general colour profile; use this only when the user explicitly wants the fingerprint format alone.' This names the alternative and specifies the exact condition for using this tool.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds valuable behavioral context by detailing the return structure (verdict, risks, required actions, light behaviour under three illuminants, substrate notes, recommended alternative) and the method (CIEDE2000 archive matching, Claude material knowledge). This goes beyond the annotation baseline, though it does not mention limitations or edge cases, 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 concise and front-loaded: it states the purpose in the first sentence, then enumerates return values, underlying method, and illustrative examples. Every sentence earns its place, and the structure is scannable. It is appropriately sized for the tool's complexity.

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

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

Given the readOnly annotation, 100% schema coverage, and an output schema, the description is quite complete. It covers purpose, outputs, method, and use-case examples. It could additionally mention limitations or explicit alternatives, but overall it provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, meaning all five parameters are already documented with descriptions in the schema. The tool description does not add specific parameter-level semantics beyond what the schema provides, though it does give examples of hex and substrate values. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Assess whether a hex colour can be safely specified for a physical application.' This clearly distinguishes it from sibling tools by emphasizing safety for physical applications, and the listed outputs (verdict, risks, actions, light behaviour, substrate notes) reinforce its unique purpose.

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

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

The description provides clear context for when to use the tool: when a physical application safety check is needed. It does not explicitly name alternatives or exclusions, but the purpose is sufficiently distinct from siblings like colour_compare or colour_metrics. Examples further illustrate appropriate use cases, earning a 4 rather than a 5.

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

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

The readOnlyHint annotation already declares the safety profile, and the description adds a modest behavioral detail about matching to 'named archive colours.' However, this phrasing is ambiguous and does not clearly explain the matching process or any limitations. No contradictions with annotations, but the added context is limited.

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 sentence that efficiently communicates the core function. Every word contributes to the meaning, with no redundant or filler content.

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

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

Given the simple two-parameter tool, the schema covers all parameters, and an output schema exists, the description is mostly adequate. However, the phrase 'named archive colours' is vague and unexplained, leaving ambiguity about how the matching works and what 'archive' refers to, which creates a minor completeness gap.

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

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

The input schema provides 100% description coverage for both parameters, so the schema already documents hex and harmony_types. The description lists some harmony types, but this adds little beyond what the schema offers, and it does not clarify the relationship between the hex and 'named archive colours.'

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 what the tool does: it returns complementary, triadic, analogous, and split-complementary harmonies. It specifies the resource (colour harmonies) and the scope (matched to named archive colours), but it does not explicitly distinguish itself from sibling tools like colour_combination or colour_mix, so it stops short of 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?

The description offers no guidance on when to use this tool versus alternatives. It simply states the function without mentioning use cases, prerequisites, or alternative tools, which is a significant gap given the large number of sibling colour-related 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 readOnlyHint annotation already indicates a safe read operation. The description adds valuable behavioral context by mentioning the provenance backing ('nearest archive colour's cultural provenance') and tunability by audience and tone, which goes beyond the annotation.

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

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

Three sentences, each with a distinct purpose: what it generates, how it is backed, and how it can be used. No redundant information, and the primary action 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?

For a read-only content generation tool with an output schema, the description covers the core functionality, customization options, provenance, and use cases. It avoids over-explaining return values, which are handled by the output schema.

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

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

Schema coverage is 100% with descriptions for all parameters. The description enriches parameter understanding by naming example values for audience ('general public, designers, historians, children') and tone ('dinner party, academic, social media, brand copy'), reinforcing the tunable nature.

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 action ('Generate a hook sentence, three-sentence story, tweet, image prompt, and follow-up questions') and its resource ('any hex colour'). The specific list of output types distinguishes it from sibling tools like colour_story, which focus on a single narrative output.

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

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

The description explicitly provides usage contexts: 'to make archive colours shareable, to generate content, or to power a public-facing colour chat experience.' It does not mention alternatives or when-not-to-use, but the intended scenarios are 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 covers the safety profile, so the description does not need to reiterate that. However, the description adds no additional behavioral context beyond the core purpose—such as whether multiple matches are returned (though the 'n' parameter hints at this) or any limitations. It is not misleading, but does not enrich beyond the annotation.

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

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

The description is a single, well-formed sentence that is immediately understandable. It conveys the essential information without any fluff or repetition, earning a high score for conciseness.

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

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

Given the tool's simplicity, the presence of an output schema, and full schema parameter coverage, the description is sufficiently complete. It does not explicitly describe the return format, but the output schema presumably addresses that. A small gap is that it does not mention the optional brand filter or the 'n' parameter, but these are documented in 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?

The input schema covers all three parameters with descriptions (100% coverage), so the description does not need to add parameter-level details. The description does not mention the optional 'brand' filter or 'n' parameter, but the schema provides adequate semantics.

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

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

The description clearly states the tool's function with a specific verb ('Find') and resource ('nearest named colour in commercial paint systems'), and it explicitly names the brands covered (Farrow and Ball and Little Greene). This distinguishes it from sibling tools like colour_mix or colour_namer, which likely serve different purposes.

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

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

The description implies usage for converting a hex value to a named commercial paint colour, but does not explicitly state when to prefer this over alternatives or provide any exclusions. The brand filter is mentioned in the schema but not in the description, so guidance on optional narrowing is absent.

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, so the tool's safe read-only nature is already declared. The description adds value by listing the specific metrics returned and positioning the tool as a component of colour_passport, which gives context beyond the annotations.

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

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

The description is two sentences, front-loaded with the action and result, followed by concise usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

Given the tool's simplicity (one parameter), the presence of an output schema, and readOnly annotation, the description fully covers purpose, usage, and relationship to related tools. It does not need to explain return values because the output schema exists, and no gaps remain.

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 full coverage (100%) with a description for hex_val including a type and example. The description does not add additional parameter-specific semantics, so the baseline score of 3 is appropriate since the schema adequately documents the 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 'Returns raw perceptual metrics (LRV, chroma, hue angle, warmth, undertone) for a single colour.' It uses a specific verb and resource, and distinguishes itself from the sibling colour_passport by noting it is a component and is meant for isolated numeric 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 explicitly provides usage guidance: 'Use colour_passport for a general colour profile; use this only when the user explicitly wants isolated numeric values.' This gives clear when-to-use and alternative tool guidance, exceeding basic context.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable context: the perceptual model used, the output structure, and an example. It does not contradict annotations. While it doesn't disclose edge cases or limitations, it provides more behavioral context beyond what annotations alone offer.

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

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

The description is only three sentences, with the main purpose front-loaded. The example sentence is illustrative and earns its place. No redundant or filler content.

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

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

Given the tool has an output schema and read-only annotations, the description sufficiently covers the purpose, model, and example output. It does not explicitly list use-case alternatives, but for selecting this tool among many colour siblings, it provides enough context to make an informed choice.

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 input schema already describes each parameter clearly. The description's example references two hex values but does not add additional semantic meaning beyond what the schema provides. Thus, baseline 3 is appropriate.

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

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

The description uses a specific verb 'Simulate' and resource 'mixing of two colours', and clearly distinguishes from RGB blending by mentioning CIE Lab subtractive model. It also specifies the output (mixed hex value and nearest archive match), making its purpose unmistakable and distinct from siblings like colour_compare or colour_harmonies.

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

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

It clearly implies usage for subtractive pigment mixing by contrasting with RGB screen blending, and provides an example scenario. However, it does not explicitly name alternative tools or state when not to use it, so it falls slightly short of full explicit guidelines.

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

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

Annotations already mark this as read-only, which is not contradicted. The description adds value by disclosing that every name is 'grounded in a real archive source' and that the tool offers 'naming styles', giving insight into output quality and behavior 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 three sentences, each earning its place: the first states the core action, the second lists style options, and the third reinforces archive grounding and the primary use case. It is front-loaded and free of fluff.

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

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

With an output schema present, return values need not be described. The description covers purpose, styles, archive grounding, and the Shopify context, making it complete for a generation tool. Optional parameters are left to the schema, which is acceptable given high 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 coverage is 100%, so the baseline is 3. The description lists style options already present in the schema and adds no extra meaning for parameters like market or n_names beyond what the schema descriptions already provide. It does not compensate with additional parameter details.

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

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

The description uses a specific verb ('Generate') with a clear resource ('colour names for any hex value') and differentiates from sibling tools by emphasizing archive-verified grounding and naming styles. It also mentions the Shopify product naming use case, which clarifies the intended domain.

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 Shopify product naming and any hex value, but it does not explicitly state when to use this tool over siblings like ecommerce_namer or colour_hooks, nor does it provide exclusions. The 'core of the Shopify product naming use case' gives some context, but no alternatives are named.

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 no destructive behavior needs disclosure. The description adds value by explaining the tool returns a canonical, exhaustive dataset and gives concrete examples, which helps set expectations. It doesn't discuss rate limits or auth, but for a read-only tool with a rich output schema, the disclosure is sufficient.

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

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

The description is longer than average but well-structured: definition, content summary, usage guidance, and examples. Every sentence contributes, though the list of data categories could be slightly more compact. It is appropriately detailed for a complex tool with many optional parameters.

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

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

Given the tool's complexity, the description provides enough context to understand its role, what it returns, and when to use it. The output schema covers specific return values, and examples ground the behavior. Minor missing context like default archive count or batching behavior is already in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description doesn't add parameter-level detail, but it doesn't need to; the schema already explains hex, hexes, n_archive, include_physics, and include_cultural with defaults and examples.

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

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

The description opens with 'Canonical single-call colour truth object' and 'Returns everything known about a hex value', clearly stating the tool's purpose and scope. It explicitly distinguishes itself from siblings by naming colour_dna, archive_provenance, colour_cultural_risk, and colour_metrics, and positions itself as the foundational call ('Every other tool is built on this data').

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 clear guidance on when to use: 'Use this as the foundation call when you need the complete picture.' It also explains when not to chain separate tools by stating it 'Replaces chaining colour_dna + archive_provenance + colour_cultural_risk + colour_metrics separately', offering a direct alternative comparison.

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 valuable behavioral context: it accepts up to 20 hex values, automatically deduplicates, and returns a full Colour Passport with listed components. It does not describe error behavior for >20 or invalid hexes, but this is acceptable given the read-only nature and output schema.

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

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

The description is concise and well-structured. It immediately identifies the tool as a batch version, then explains the input limit, output contents, deduplication, and use cases. Every sentence adds essential information 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 output schema exists, return values don't need detailed explanation. The description covers the main use cases, input constraints, and deduplication behavior. It is complete enough for a batch tool but could optionally mention error handling for excessive inputs or invalid hex values.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by highlighting the 'up to 20 hex values' limit and the automatic deduplication behavior, which directly clarifies how the hexes array input is processed.

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

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

Clearly identifies itself as the batch version of colour_passport with a specific verb+resource+scope: submit up to 20 hex values and receive full Colour Passports. It distinguishes itself from the singular sibling tool by explicitly mentioning batch processing and deduplication.

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

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

States exactly when to use this tool: multi-colour workflows, Figma palette analysis, or any case where calling colour_passport separately would be slow. This explicitly points to the alternative (colour_passport) and provides clear use cases.

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 annotation, the safety profile is already known. The description adds useful behavioral context: names are 'archive-grounded' and use 'dE2000 distance', which informs how the tokens are derived. No contradiction.

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

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

Two tightly crafted sentences. The first sentence lists concrete outputs, and the second adds source and matching detail. No filler or redundancy.

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

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

An output schema exists, so return values are documented. The description covers purpose, input hex, optional archive dimension, and the naming logic (archive-grounded, dE2000 distance), making it sufficiently 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?

Schema coverage is 100%, so the parameters are already documented (hex, archive). The description mentions 'hex value' and 'archive-grounded' but does not add significant new parameter-level semantics beyond the schema.

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

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

The description clearly states the tool returns every developer token format for a hex value, enumerating specific formats (CSS variable, kebab-case, etc.), which distinguishes it from sibling naming tools like colour_namer or colour_variants.

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 clear usage: when you need developer token formats for a hex value. It does not explicitly mention alternatives or exclusions, but the scope is unambiguous and the sibling list shows related tools with different purposes.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context beyond that: it explains the output is a narrative covering history, cultural meanings, and archive names, with a concrete example. It does not disclose internal mechanics but the example and output description give a solid sense of behavior, so no contradiction and good added value.

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: the main action, the use-case rationale, and a concrete example. It is front-loaded with the core purpose, every sentence earns its place, and there is 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 tool's low complexity (2 parameters), the presence of an output schema, and clear annotations, the description is complete. It covers what the tool does, when to use it, what the output looks like via the example, and how it differs from siblings, so no critical gaps remain.

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 'hex' and 'n_archives' already described in the schema. The description's example hex value '#DC143C' repeats the schema's example and adds no new parameter meaning. While the description implies the narrative's breadth, it does not enhance parameter understanding beyond the schema, 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 takes a hex value and returns a rich narrative about that colour's cultural journey, including historical appearances, meanings across civilisations, and archive names. This specific verb+resource+outcome distinguishes it from siblings like colour_timeline or colour_dna, which likely focus on different aspects.

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

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

The description provides clear usage context by listing use cases: 'Essential for image generation prompts, brand storytelling, and creative briefs' and gives a concrete example output. However, it does not explicitly mention when not to use this tool or name alternative tools for other scenarios, so it falls short of a 5.

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

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

The description goes well beyond the readOnlyHint annotation by detailing what the tool computes and returns: archive grounding, verdict, brand fit, market risk, category cliche check, material behaviour, copy hooks, and usage rules. It also lists the structured output fields and provides concrete examples. 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 dense but well-structured: it opens with the one-line purpose, then lists the combined analyses, inputs, outputs, and examples. Every sentence provides essential information, and the use of 'Input:' and 'Output:' labels makes it scannable. 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?

For a tool with 5 parameters, nested objects, and an output schema, the description is remarkably complete. It covers all input types, enumerates the major output sections, and gives four varied examples. The existence of an output schema reduces the burden to explain return values, so this description is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema has 100% parameter description coverage, so the baseline is 3. The description's 'Input:' line simply recaps the parameter names already present in the schema (hex, brand_context, constraints, markets, medium) without adding new semantic detail. It does not deepen the meaning of any parameter 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 a specific verb+resource: 'Single-call commercial colour strategy report.' It enumerates the combined analyses (archive grounding, verdict, brand fit, market risk, etc.), which distinguishes it from the many sibling tools that focus on individual aspects. This is a definitive, non-tautological 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 phrase 'Single-call commercial colour strategy report' clearly implies using this tool when a complete strategy is needed in one call rather than assembling it from separate tools. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds behavioral context by stating the output is 'dated sequence', 'chronological order', and includes 'primary sources.' The example with 'indigo' illustrates the multi-century scope, giving agents a clear model of how the tool behaves.

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

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

The description is compact and well-structured: first sentence states the action and output, second gives usage scenarios, third provides an illustrative example. No redundant words, and each sentence adds distinct 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?

The tool has a good output schema and read-only annotation. The description covers functionality, usage, and parameter semantics with an example that ties everything together. For a tool of this complexity, it is fully self-contained and leaves no critical gaps.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description enriches the 'concept' parameter by providing concrete examples ('indigo', 'imperial purple', 'mourning black'), which helps agents understand what constitutes a valid input beyond the schema's generic description.

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

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

The description clearly states the tool's function with a specific verb ('traces') and resource ('documented appearances across cultures and centuries'), and specifies the output format (dated sequence of archive entries with primary sources). This distinguishes it from sibling tools like archive_provenance or colour_story, which likely focus on different aspects of history or narrative.

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 lists use cases: 'historical research, provenance chains, and understanding why a colour carries the cultural weight it does.' While it doesn't name alternative tools or state when not to use it, these concrete scenarios provide clear guidance for when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true, and the description adds behavioral detail by enumerating the types of results returned (historical, lighter/darker, archive matches, cultural siblings). It does not contradict annotations and provides useful context beyond the flag.

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

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

Two sentences, front-loaded with the core action and output, no redundant words. The second sentence adds a brief audience/use-case note without bloat.

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 a simple one-parameter input, the description fully covers what the tool does and when to use it. No gaps remain for the agent to select and invoke it correctly.

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

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

Schema description coverage is 100% and the single parameter 'name' already has an example ('Bourton Honey'). The description reinforces 'named archive colour' but does not add substantive meaning beyond the schema, 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 uses a specific verb ('return') and clearly identifies the resource: 'historical variants, lighter and darker versions with archive matches, and cultural siblings.' This distinguishes it from sibling tools like colour_compare or colour_harmonies by specifying the unique output.

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

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

States 'Essential for designers exploring around a colour,' which conveys a clear use case and context. It does not explicit mention when not to use or name alternatives, but the context is strong enough for a one-parameter 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?

With readOnlyHint=true, the annotation already declares safety. The description adds meaningful context by detailing the verdict options, output components (strengths, risks, alternatives), and the underlying methodology (CIEDE2000 + cultural intelligence). This goes beyond the minimal annotation, though it doesn't discuss response size 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 three sentences plus examples. It is front-loaded with the core action and returns, then adds methodology and concrete examples. Every sentence contributes, though the example list is slightly longer than strictly needed—still well under any verbosity threshold.

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

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

Given the tool's moderate complexity (5 parameters) and the presence of an output schema, the description covers the essential context: what it does, what it returns, and practical usage scenarios. It doesn't need to enumerate return fields, but it could have briefly mentioned how the verdict is derived for full completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value by illustrating parameter combinations through examples (e.g., 'heritage interior lime plaster wall' ties use_case and medium together). It clarifies how parameters interact without duplicating schema definitions.

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

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

The description clearly states the tool evaluates a hex colour for a specific use case, market, and medium, and returns a decisive verdict. This specific verb+resource combination distinguishes it from sibling tools like colour_cultural_risk (which focuses only on cultural risk) and palette_verdict (which likely targets whole 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 implies when to use via examples like 'luxury hotel brand in Japan' and 'ecommerce CTA button UK', showing applicability across use cases and markets. It doesn't explicitly name alternative tools or exclusion scenarios, but the context is clear enough for an agent to select this for single-colour use-case evaluations.

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 include readOnlyHint=true. The description adds meaningful behavioral context: it is a compound tool that internally chains multiple operations, returns a package with multiple components, and is not suited for iterative refinement. It doesn't mention potential performance implications or limitations, but for a read-only operation, the provided transparency 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 concise and well-structured: only two sentences, front-loaded with the core concept ('One-call compound tool'), and efficiently enumerates the outputs and usage context. Every sentence contributes value 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?

For a complex compound tool, the description covers purpose, output components, usage scenarios, and exclusions. Output schema handles return values, so that is not a gap. The only minor omission is not explaining how 'audience' (mentioned in the description) maps to parameters, but overall it is fairly 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?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds a high-level summary of inputs ('concept, medium, audience, and constraints') but introduces ambiguity by mentioning 'audience' which is not an actual parameter. It does not add significant format or syntax details beyond what the schema already provides.

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

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

The description clearly identifies the tool as a 'one-call compound tool' that takes a concept and produces a complete design package, listing concrete outputs (palette, cultural narrative, paint matches, accessibility check, etc.). It distinguishes itself from siblings by explicitly naming the individual tools it replaces (query_conceptual, palette_from_concept, colour_story, etc.).

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 when an AI agent or user needs a complete, deployable colour direction in a single call' and 'Not for iterative refinement — use individual tools for that.' It also names the alternatives, making the when/when-not distinction very clear.

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

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

Annotations provide readOnlyHint=true, and the description adds meaningful behavioral context: every piece of copy is grounded in archive provenance, the colour name comes from the nearest archive match (not invented), and output is never generic AI copy. This goes beyond the annotation by setting expectations about grounding and provenance 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 contributes: purpose, input/output summary, provenance guarantee, examples, and target use cases. It is front-loaded with the main action and structured logically, 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?

The description fully explains what the tool does, the output items, key behavioral traits (archive provenance), examples, and relevant channels. Since an output schema exists, return values need not be detailed. Given the tool's complexity, 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 input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds value through examples that illustrate parameter combinations (e.g., 'velvet cushion in Murex Luxury') and clarifies the purpose of hex and product_type, but does not deeply explain each parameter beyond schema coverage.

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

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

The description clearly states the tool generates complete ecommerce product copy for any colour, with specific outputs listed. It distinguishes itself from siblings like ecommerce_namer and palette tools by focusing on full product copy grounded in archive provenance, not just naming or palette analysis.

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

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

The description clearly indicates the tool is for ecommerce product copy generation and mentions channels like Shopify, WooCommerce, and editorial. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations declare readOnlyHint=true, and the description does not contradict this. It adds valuable behavioral context: 'Every name is archive-sourced, not invented' and 'Each carries a primary source citation that can be defended to buyers, press, and brand teams', which clarifies the guarantee of traceability.

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-organized with a clear input/output structure, and every sentence contributes meaningful information: scope, use cases, guarantees, and options. It is detailed yet efficient, avoiding redundancy with the schema by specifying unique attributes like 'up to 40 SKUs' and 'dE2000 match distance'.

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 coverage, the description need not repeat return structures, but it enriches understanding by explaining the output semantics (source citation, dE2000, confidence). It covers input, output, use cases, and constraints, making the tool fully comprehensible to an agent.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description mentions the general input types (hex values, category, brand, style) but does not add new details beyond what the schema provides, keeping this at the 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 opens with a specific verb phrase 'Generate archive-grounded colour names for up to 40 product SKUs', clearly defining both the action and resource. It also distinguishes itself from sibling tools like colour_namer by emphasizing 'archive-grounded' and 'product SKUs'.

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 use contexts: 'Use for paint ranges, candle collections, fashion lines, homeware, cosmetics.' However, it does not explicitly name alternatives or state when not to use this tool, though the archive-grounded nature implies differentiation.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds behavioral context like optional archive matching (analyse, style_context) and the ingest_image dependency flow. However, it doesn't describe the return shape or what happens with conflicting inputs (both image_url and image_id given), and 'ephemeral' image_id isn't elaborated.

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

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

Description is compact and front-loaded with the core purpose, then branches into usage guidance. No wasted words. Minor deduction for slight redundancy between the ingest_image explanation in prose and the image_id parameter description.

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

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

With 7 params, 0 required, an output schema, and readOnlyHint annotation, the description covers the key decision points: which input to use and when, plus the optional analysis features. Missing behavioral details like behavior on conflicting inputs or error conditions, but the output schema covers return values. Adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds some value by linking image_id to ingest_image and explaining when each input source applies, plus clarifying style_context's purpose (cultural naming coherence). But with full schema coverage, the description correctly leaves heavy lifting to the schema.

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

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

Description clearly states verb+resource ('Extract dominant colours from a photograph') and differentiates method (proprietary k-means++). It distinguishes from siblings: mentions ingest_image for raw uploads and positions it 'before image_brief'.

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

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

Provides explicit when-to-use ('Use this before image_brief when you have an uploaded photograph') and when-not-to ('If you only have a raw uploaded file... call ingest_image first'). Also clearly explains alternative path when no public URL exists.

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, it discloses the grouping logic (provenance vs perceptual), the meaning of grouping_basis and provenance_credit, that historical claims are only templated from actual record fields, and that orientation doesn't affect selection. It also warns about response size, adding rich 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?

It's a long description, but each sentence contributes: purpose, grouping rules, output contents, evidence disclosure, orientation caveat, example, sibling guidance, and house_ref handoff. It's front-loaded with the core purpose, 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?

Given the tool's complexity (multi-room, provenance grouping, output schema), the description covers the key behaviors, limitations, and downstream usage. The presence of an output schema means return values needn't be detailed here, and the description still mentions house_ref for PDF generation, making it very 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 already provides 100% coverage of all 9 parameters with explanations. The description only adds an example and restates the orientation caveat already present in the schema, so it adds little beyond the 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 opens with 'Generate a complete multi-room house colour scheme from a single archive' — a specific verb and resource. It explicitly contrasts with the sibling 'interior_specify' for single-room use, making differentiation 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?

It states 'Use interior_specify instead for a single room without cross-room grouping,' which is an explicit alternative and exclusion. The opening phrase also establishes the multi-room, single-archive context, giving clear when-to-use guidance.

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

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

With readOnlyHint=true, the safety profile is already covered by annotations. The description adds meaningful behavioral context by outlining the internal pipeline (extract, match, understand, identify, suggest, generate, return) and mentioning the swatch URL output. It does not disclose limitations like auth, rate limits, or failure modes, but the added context goes beyond what annotations provide.

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

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

The description is 3 sentences with no filler. The first sentence is dense but information-rich, front-loading the compound nature and outputs. The second and third sentences provide alternatives and usage tips. While not as minimal as a two-sentence example, 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?

The tool is complex with 8 parameters and an output schema. The description covers the compound workflow, mentions the alternatives it replaces, and gives usage guidance for style_context. Since the output schema exists, return values are covered, and schema covers all parameters. The description is sufficiently complete for an agent to select and call 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?

Input schema covers 100% of the 8 parameters with their descriptions, so the baseline is 3. The description adds value for style_context with specific examples ('English cottage garden', 'Victorian', 'MarsColour') and notes product categories (textiles, interiors, fashion) that align with product_type. However, most parameter semantics live in the schema, and the description does not compensate for any uncovered gaps.

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

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

The description opens with 'Compound endpoint: one image in, full creative brief out' and enumerates specific outputs: colour extraction, archive matching, cultural naming, scene understanding, style period, product directions, prompt generation, and swatch URL. This clearly states the tool's function and differentiates it from siblings by explicitly mentioning the alternative chaining workflow.

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

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

The description provides explicit usage guidance: 'Use instead of chaining palette_extract + palette_analyse + agent_brief separately' and instructs to 'Pass style_context for coherent archive matching'. This clearly indicates when to use the compound endpoint versus alternatives. It lacks explicit 'when not to use' conditions, but the guidance is substantial.

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

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

Annotations already declare readOnlyHint=true, so the description goes beyond structural data by adding meaningful behavioral details: the image is never stored and is processed in memory only. It also discloses the algorithm (K-means++ and Bradford chromatic adaptation) and the specific output fields, which helps the agent understand what to expect.

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

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

The description is highly concise, with three sentences that each serve a distinct purpose: stating the core function, explaining the technical approach, and listing use cases plus a privacy guarantee. No filler or redundant phrases are present.

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

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

Given the tool has an output schema and modest complexity (4 parameters, 1 required), the description covers all key aspects: input format, algorithm, output contents, supported use cases, and data handling. It is complete enough for an agent to select and invoke the tool correctly without further clarification.

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 documentation covers 100% of parameters (image_base64, archive, n_colours, media_type) with clear descriptions, so the description does not need to compensate. It reinforces that the image is base64 encoded and that n_colours is capped at 5, but adds no new semantic details beyond the schema.