Colour Memory

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

Annotations already declare readOnlyHint=true, so the description's claim of evaluating contrast (a read operation) is consistent but adds little beyond that. The description does add scope constraint (single pair) which is useful but not about behavior beyond safety.

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

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

Two sentences, no wasted words, front-loaded with core purpose, then alternative. Efficient and clear.

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, good annotations, and presence of output schema, the description is complete: covers what, when, and alternatives.

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

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

With 100% schema description coverage, the schema already documents both parameters. The description adds minimal additional meaning beyond implying foreground and background roles.

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

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

The description clearly states it evaluates contrast for a single foreground/background pair, using a specific verb ('evaluates contrast') and resource. It distinguishes itself from the sibling tool 'accessibility_matrix' which handles 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 explicitly tells when to use this tool (single pair) and when to use the alternative (accessibility_matrix for palettes), providing clear 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 indicate readOnlyHint=true, which is consistent. Description adds context by specifying output includes WCAG grades and recommendations, which is beyond the input schema. No mention of side effects or mutations, so it's transparent.

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

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

Single sentence, no redundancy. Front-loaded with key information: inputs, output, and relevant details. 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 two-parameter schema and existence of an output schema (though not shown), the description adequately explains the tool's functionality and output. Could mention any prerequisites or limitations, but not necessary for clarity.

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. Description restates the parameter roles and adds 'candidate' context, but doesn't provide additional constraints or details beyond what the schema already offers.

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

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

Description clearly states the action (return ranked list), resource (foreground colours for a background), and output details (WCAG grades, recommendations for text/UI). It effectively distinguishes from siblings like accessibility_check and 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?

No explicit when-to-use or when-not-to-use guidance is given. The purpose implies contrast evaluation, but alternatives among sibling tools are not mentioned.

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

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

Annotations already indicate readOnlyHint=true. The description adds behavioral detail about what is returned (contrast ratio, pass/fail grades, summary) without contradicting annotations. It lacks disclosure of potential performance or rate limits, but the annotations cover safety.

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 effectively convey purpose and usage guidance. No redundant or unnecessary text. Front-loaded with the primary function.

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

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

Given the output schema exists, the description covers the essential behavioral aspects (foreground/background combinations, contrast ratios, grades, summary). Constraints on palette size are in the schema. The information is 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 description coverage is 100%, with a clear example in the schema. The tool description does not add new semantic detail beyond reinforcing that the parameter is a palette array. Baseline 3 is appropriate.

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

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

The description explicitly states the tool accepts a palette array and returns detailed accessibility grades (contrast ratio, AA/AAA pass/fail) for every foreground/background combination. It directly distinguishes from the sibling 'accessibility_check' by positioning itself as the batch alternative.

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

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

The description includes 'Use this instead of calling accessibility_check multiple times for a palette.' This provides clear guidance on when to use this tool versus the alternative, aiding 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?

Beyond the readOnlyHint annotation, the description adds deterministic behavior and no LLM cost, and explicitly lists output categories, providing transparency about what the tool returns.

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

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

The description is two sentences, front-loaded with the primary action, and contains no redundant information. Every sentence adds value.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description adequately covers inputs, outputs, and key traits. It could be slightly more detailed about usage context, but overall sufficient.

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

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

With 100% schema coverage, baseline is 3. The description adds context that the input is a 'palette' for generating rules, but does not elaborate on constraints or format beyond the schema's 'Array of hex values'.

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

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

The description clearly states the tool's action ('Convert a palette WCAG matrix into actionable design-system rules') and enumerates specific outputs, distinguishing it from siblings like accessibility_check which likely handles individual pair checks.

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

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

The description does not explicitly state when to use this tool over alternatives like accessibility_check or accessibility_matrix. While it hints at efficiency with 'Deterministic, no LLM cost', it lacks direct guidance on context or exclusions.

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

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

Annotations already declare readOnlyHint=true, and the description adds that it 'simulates' using a specific model (Brettel-Vienot-Mollon), which clarifies it doesn't modify anything and relies on a well-known algorithm. No contradictions. The description provides useful context beyond annotations.

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

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

The description is a single sentence of 15 words, front-loaded with the key action and result. No unnecessary words.

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

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

Given the low complexity (one parameter, output schema exists, clear annotations), the description sufficiently covers the tool's behavior and return value. It names three specific outputs and the algorithm, which is complete for this use case.

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 single parameter 'hex_val' described as 'Hex value e.g. '#BE0032''. The tool description implies the parameter is the input color to simulate, but doesn't add details on constraints or format beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'return' and the resource: simulated hex values for protanopia, deuteranopia, and tritanopia using the Brettel-Vienot-Mollon model. It distinguishes this tool from siblings like accessibility_check (which likely checks contrast) and colour_compare, as it focuses on simulating color blindness.

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 provided on when to use this tool versus alternatives. The description does not mention when not to use it, prerequisites, or context. With many sibling tools, this lack of direction could lead to confusion.

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 set readOnlyHint=true, and the description adds behavioral details: fetching archive palette, supporting multiple models, and locked_palette skipping archive query. No contradiction. The description enhances awareness of tool behavior beyond annotations.

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

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

Two paragraphs and an example, front-loaded with purpose. Every sentence adds value; no verbosity. Efficiently communicates core functionality, outputs, and key options.

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 8 parameters and existence of output schema, the description covers the workflow (fetch → produce outputs), lists all output types, explains model support, and details locked_palette behavior. Sufficient for correct invocation.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: it explains that locked_palette bypasses archive queries and that archive is historically grounded. The description enriches parameter understanding.

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

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

The description clearly states it generates a 'complete colour direction package' for another AI agent, listing specific outputs (archive palette, brief, tokens, prompts, lighting notes). It distinguishes itself from sibling tools like palette_generate or colour_strategy by explicitly serving as the color layer for external AI systems.

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 (e.g., 'Use this to make Colour Memory the colour layer for other AI systems') and an example, implying when to use. However, it does not explicitly state when NOT to use this tool versus alternatives, missing 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 declare readOnlyHint: true, consistent with the read-only 'verify' operation. The description adds detailed output specifications (fidelity score, dE2000, match quality, verdict) that go beyond annotations, enhancing 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 three sentences, front-loaded with purpose, then inputs, then outputs and usage. Every sentence contributes value; no wasted words.

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

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

Given the presence of an output schema, the description still details return values, making it self-contained. However, it lacks error handling information (e.g., invalid image, missing palette) and assumes familiarity with agent_brief.

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

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

Schema description coverage is 100%, so the description repeats schema info (e.g., 'URL of the generated image'). It adds context about target_palette being from agent_brief colour_tokens, but does not clarify that one of image_url or image_base64 must be supplied, leaving a minor gap.

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 specific action ('Verify that an AI-generated image actually used the colours'), identifies the resource (image colour fidelity), and ties it to a specific context (after agent_brief call), differentiating it from siblings like colour_compare or palette_compare.

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

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

The description explicitly says 'Use after agent_brief + image generation to close the colour loop', providing clear context. It does not explicitly list when not to use or alternatives, but the workflow implication is strong.

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

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

Annotations already declare readOnlyHint=true, but description adds behavioral traits: outputs a one-liner, short story, and tweet; involves finding contradiction in archive; mentions Claude writes creatively. 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?

Front-loaded main purpose, includes concrete example, and lists use cases. Every sentence contributes value without redundancy. Highly efficient.

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

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

Given tool complexity (creative generation) and presence of output schema (not shown), description adequately covers purpose, parameters, example, and use cases. Would benefit from mentioning output format details, but output schema likely covers 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 coverage is 100%, baseline 3. Description adds meaning by explaining 'expected_colour' as 'cliche colour to contradict' with example 'red', and 'n_results' implied in archive search context. Goes beyond schema definitions.

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

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

Clearly states verb 'find' and 'generate' with specific resources: 'archive colour' and 'memorable one-liner'. Distinguishes from sibling tools focusing on palettes, audits, or color utilities by emphasizing creative subversion of cliches.

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 example (love + red) and usage context ('public-facing demos, content, brand storytelling'). Lacks explicit when-not-to-use or alternatives, but the example and context sufficiently guide the agent.

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

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

The description details the output: 'Returns a coverage matrix: for each theme, entries found, coverage grade (strong/moderate/weak/missing), best match with claim strength, and what source type would be needed.' This adds significant context beyond the readOnlyHint annotation, which indicates no destructive behavior.

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

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

The description is concise: two main sentences plus a brief usage note and a warning. It is front-loaded with the core functionality, and every sentence provides necessary information without redundancy.

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

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

Given the tool has only 2 parameters, 100% schema coverage, readOnlyHint annotation, and an output schema (implied), the description is complete. It explains the return structure, the ideal use case, and the rationale, covering all aspects an agent needs.

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

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

The input schema has 100% description coverage for both parameters. The description adds value by clarifying the purpose of 'themes' and the optional nature of 'archives' ('Optional archives to search'), but does not repeat schema details. The baseline of 3 is elevated due to added context about usage.

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

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

The description clearly states the tool's purpose: 'Given a list of themes, report which are well-evidenced in the archive and which are under-evidenced or missing.' It specifies a verb ('report') and resource ('coverage gap'), and differentiates from siblings by explicitly mentioning usage before archive_report_brief or 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 provides explicit when-to-use guidance: 'Use this BEFORE building an archive_report_brief or brief_forensic.' It also warns against misuse: 'Prevents building beautiful reports that quietly ignore half the brief.' Sibling tools like archive_evidence_gap and archive_report_brief are implied alternatives.

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

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

Annotations indicate readOnlyHint: true, and the description ('Check', 'Detects') aligns with a read-only operation. The description adds behavioral context by detailing the output fields (anachronism_risk, period_relevance, safe/unsafe phrasing). No contradictions.

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

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

The description is three sentences: first states the main action, second adds detection details, third provides a practical example. It is front-loaded, concise, and contains no superfluous words.

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

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

Given the presence of an output schema and 100% parameter description coverage, the description sufficiently explains the tool's purpose and output. It covers the key behavioral aspects needed 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?

All four parameters have descriptions in the input schema (100% coverage). The description adds value by explaining how parameters are used: checking primary source date against period and detecting known modern archives. It also clarifies the output format.

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

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

The description clearly states the tool's purpose: 'Check a list of colour entries for anachronism risk.' It specifies detection criteria (primary source date, known modern archives) and output (period_relevance score, safe phrasing). This distinguishes it from sibling tools like archive_audit or archive_cliche.

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

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

The description provides a concrete usage example: 'prevents a 2011 Jockey Club racing silk registration being presented as Georgian evidence.' It implies usage for historical document validation, though it does not explicitly exclude alternative tools or scenarios.

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

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

Annotations indicate readOnlyHint=true, and the description adds behavioral context: it is an anti-hallucination endpoint that transforms absence of evidence into a forensic finding. This adds value beyond annotations, though it could mention permissions or rate limits.

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

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

The description is concise, with key information front-loaded: input, output, purpose, example, and use cases. Every sentence earns its place; no fluff.

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

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

Given the presence of an output schema (implied), the description covers input, process, output structure, and use cases adequately. It could briefly mention error handling or required permissions, but overall complete.

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

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

Schema coverage is 100%, so the description does not need to add parameter details. It does provide a concrete example linking hex and proposed_claim, which aids understanding, but does not go beyond schema descriptions.

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

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

The description clearly states the tool's purpose: given a hex value and a proposed claim, it returns archive support, missing evidence, needed source type, and safe wording. It distinguishes itself as an 'anti-hallucination endpoint' for forensic workflows, setting it apart from sibling tools.

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

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

The description implies usage for museum, documentary, editorial, legal, and forensic workflows, but does not explicitly state when to avoid using this tool or mention alternatives among the many sibling tools like archive_search or archive_coverage_gap.

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

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

Annotations already mark readOnlyHint=true, so no contradiction. Description adds behavioral context: explains types of provenance, confidence, citation format, and that it's a component of colour_passport. Useful beyond annotations.

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

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

Two concise sentences: first defines purpose and output, second provides usage guidance. No wasted words.

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

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

Given the tool's complexity and presence of output schema, the description sufficiently explains what the tool does, its outputs (provenance types, confidence, citations), and its relationship to colour_passport.

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 single parameter colour_name and examples. Description does not add further parameter meaning, but baseline is 3 as schema is adequate.

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

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

The description clearly states it explains provenance of a named archive colour, detailing three types (documented fact, computational derivation, cultural interpretation) and includes confidence and citation format. It distinguishes itself from colour_passport by noting it's for deep provenance work.

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

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

Explicit guidance: 'Use colour_passport for a general profile; call this directly for research workflows needing full source-chain detail.' This provides clear when-to-use and alternative.

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

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

Annotations already declare readOnlyHint=true; the description adds useful behavioral context like 'Two Claude calls total' and describes the rich output. It does not contradict annotations. It could mention that it triggers internal calls but remains read-only.

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

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

The description is front-loaded with the core purpose and lists inputs/outputs efficiently. It provides replacement guidance and usage instruction. Slightly verbose in enumerating all output fields, but each sentence adds value.

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

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

Given the tool's complexity (7 params, output schema exists, many siblings), the description covers input, output, usage context, and alternatives. It could mention potential limitations or prerequisites, but overall it's 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%, so parameters are already well-documented. The description lists them and adds minimal extra context (e.g., default for n_colours), but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states it's a 'one-call complete archive research package' for documents, PDFs, or editorial briefs. It lists specific inputs and outputs, and distinguishes itself from sibling tools by explicitly saying it replaces chaining multiple separate tools (archive_search, get_colour_card, 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 explicitly says 'Replaces chaining archive_search + get_colour_card + cliche_breaker + agent_brief separately.' and 'Use this first for any document workflow.' This gives clear guidance on when to use this tool versus its alternatives.

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

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

Annotations declare readOnlyHint=true, indicating a safe read operation. The description does not contradict this and adds that the search is full-text and covers specific fields. No additional behavioral traits like rate limits or permission requirements are mentioned, but the description is consistent and adequate given 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 with no filler. It front-loads the core purpose and succinctly adds differentiating context. Every sentence earns its place; no wasted words.

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

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

Given the 7 parameters (only 1 required), an output schema exists, and annotations are present, the description adequately covers the tool's behavior. It explains the include_full parameter's effect and the archive filtering option. No gaps remain for an agent to select or 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 input schema has 100% description coverage. The description adds value by providing example search terms ('cerulean, Prussian, Ottoman, ochre, medieval') and implying the use of year_from/year_to for historical periods, which goes beyond the schema. This enhances understanding without being redundant.

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

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

The description clearly states the tool performs full-text keyword search across archive colour names and notes, listing searchable aspects (name fragment, material, cultural reference, etc.) and explicitly distinguishes it from conceptual embedding search. This is a specific verb+resource with sibling differentiation.

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 mentions that this tool 'complements conceptual embedding search with exact keyword matching,' giving context on when to use this over the likely sibling tool 'query_conceptual.' It doesn't provide explicit when-not-to-use or exhaustive alternatives, but the hint is clear and useful.

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. The description adds behavioral traits: 'Deterministic. No LLM cost.' This goes beyond the annotation by clarifying cost and determinism. No contradictions.

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

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

The description is concise with four brief statements. It front-loads the key outputs. However, the structure is slightly fragmented; could be consolidated into one sentence. Still earns its place without redundancy.

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

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

Given 5 parameters with full schema coverage, an output schema, and read-only annotations, the description adds value by listing concrete outputs and behavioral traits. It is mostly complete, though it omits mentioning that palette is required.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema provides. It lists outputs but not parameter constraints or meanings.

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

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

The description clearly states it returns a complete brand asset pack with specific outputs (CSS variables, Tailwind config, Figma tokens, etc.). It explicitly distinguishes itself from other tools like brand_audit or palette_export by focusing on exporting a comprehensive pack.

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

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

The description implies use when a full brand asset pack is needed, and mentions deterministic behavior and no LLM cost. However, it lacks explicit when-not-to-use or alternative tools, leaving some ambiguity vs sibling export tools like palette_export.

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

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

Annotations declare readOnlyHint=true, and description reinforces this with 'All computed data -- no LLM cost', indicating no side effects. No contradictions; description adds details about return structure (WCAG matrix, cultural risk, etc.) beyond annotations.

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

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

Description is efficiently front-loaded with purpose and output list. Every sentence adds value, though slightly verbose in listing returns. No wasted words.

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

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

With 5 parameters and an output schema present, description covers all inputs, outputs, and usage notes. It explains the holistic nature of the tool, making it complete for decision-making.

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

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

Schema description coverage is 100%, so baseline is 3. Description mentions parameters and their roles but adds little new detail beyond schema. It lists them in use but doesn't elaborate on syntax or constraints.

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

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

Description clearly states 'Complete brand colour intelligence audit in one call' and lists specific outputs, distinguishing it from siblings like accessibility_matrix and palette_verdict. The verb 'audit' with 'brand colour' provides a precise resource and action.

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

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

Explicitly says 'Replaces chaining accessibility_matrix + cultural_risk_assessment + palette_verdict separately', telling when to use this tool instead of alternatives. Also advises to 'Pass results to an LLM for written narrative'.

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 fully discloses the tool's behavior: it returns CIEDE2000 distance, archive context, distinctiveness score, ownership verdict, verdict summary, and strategic recommendation. This goes well beyond the readOnlyHint annotation, which already indicates no side effects. There is no contradiction with annotations.

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

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

The description is two sentences: a clear purpose question followed by listing inputs and outputs, plus a usage statement. It is front-loaded, concise, and every sentence adds value. No redundant or unnecessary text.

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

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

Given the tool has 6 parameters, an output schema (not shown but mentioned), and annotations, the description is complete. It explains the purpose, required inputs, outputs, and when to use. An agent has sufficient information 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?

All 6 parameters have descriptions in the input schema (100% coverage). The description restates the inputs in prose but does not add new semantic meaning beyond what the schema provides. With full schema coverage, a score of 3 is appropriate.

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

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

The description clearly states what the tool does: checks if a brand can own a colour against competitors in a given market. It distinguishes from sibling tools by specifying it replaces manual colour distance checks and competitor palette analysis, and the question format directly defines the purpose.

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

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

The description explicitly says 'Use before committing to a brand colour in a competitive market,' providing clear context for when to use. It does not list when not to use or explicitly mention alternative tools, but the context is sufficient for an agent to determine appropriate usage.

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

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

Annotations declare readOnlyHint: true, and the description confirms it 'runs entirely internally' and 'cannot be blocked by agent safety filters.' It also mentions 'Two Claude calls total,' which is a behavioral detail beyond annotations. No contradictions.

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

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

The description is only three sentences but packs significant detail. The first sentence is dense but informative. Minor improvement would be to break the long list of outputs into a bulleted format for readability.

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 parameters (1 required), nested objects, and a complex output schema, the description provides a thorough overview of inputs, key outputs, and behavioral constraints (internal execution, no chaining). It covers all necessary context for an agent to use 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 parameter info is already present. The description adds a concise summary of key inputs: 'Input: hex + brand context + markets + medium + product type,' which helps agents quickly grasp parameter intent.

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

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

The description clearly states it produces a 'complete brand colour intelligence report' and lists many specific outputs. It distinguishes from siblings by recommending this instead of chaining multiple separate tools.

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

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

Explicitly advises use instead of chaining several other tools: 'Use this instead of chaining colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief separately.' Also notes it runs internally and cannot be blocked by safety filters.

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

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

The description explicitly states 'Deterministic. No LLM cost,' which adds behavior beyond the readOnlyHint annotation. It signals fast, consistent, non-generative results—valuable for an agent deciding to call this tool.

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

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

Two sentences, front-loaded with the core purpose, and each component of the output is listed succinctly. No redundant or extraneous information. Efficient communication.

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 explain return values. It covers purpose, behavior, and outputs. However, it does not address how it differs from several sibling tools that also produce colour systems (e.g., palette_concept, palette_light_dark), which slightly reduces 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 the baseline is 3. The description does not add extra meaning to any parameter; it only repeats that the tool uses a palette. No parameter-specific guidance is provided beyond the schema.

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

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

The description clearly states it returns a 'complete brand colour system' and lists specific outputs (colour roles, light/dark maps, typography, usage rules, design tokens). This distinguishes it from sibling tools that cover only parts of the brand system (e.g., colour_card, palette_export).

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

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

The phrase 'in one call' implies it is a one-stop solution, but there is no explicit guidance on when to use it versus alternatives (e.g., palette_specify, brand_audit). The description lacks context about prerequisites or scenarios where another tool might be more appropriate.

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 does not need to restate safety. The description adds value by specifying the return content (hex, archive, provenance, cultural notes), providing transparency about what the tool outputs beyond the schema.

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

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

The description is a single sentence, front-loaded with the action and resource, and contains no redundant information. Every word is necessary and adds value.

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

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

For a simple lookup tool with an output schema, the description covers the essential purpose and return fields. It is complete given the low complexity and availability of structured information.

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 parameter details are already present. The description adds extra context by stating that slug is preferred over name for reliable retrieval, which goes beyond the schema description and aids parameter selection.

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

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

The description uses a specific verb ('look up') and identifies the resource ('named colour'), listing the returned fields (hex, archive, provenance, cultural notes). This clearly differentiates it from sibling tools that involve comparing, mixing, or generating colours.

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

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

The description implies when to use (when a colour name or slug is available) but does not explicitly state when not to use or mention alternatives. Context and sibling names provide some differentiation, but explicit guidance is missing.

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

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

Description does not contradict readOnlyHint annotation. It mentions return outputs but adds no behavioral context beyond what annotations provide (e.g., no mention of color blindness checks or performance constraints).

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

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

Single, well-structured sentence with no fluff. All necessary information (inputs, outputs, context) is present and front-loaded.

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

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

With only 2 parameters and output schema defined, description fully covers what the tool does, its inputs, and return values (harmony, clashes, contrast, rules). No gaps.

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

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

Schema coverage is 100%, but description adds value: clarifies array length (2-5 hex values) and expands context options (UI, data viz, fashion, interior, print, branding) beyond schema's default 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?

Title and description clearly state the tool assesses 2-5 colors as a combination for a given context. It lists specific outputs (harmony type, clash warnings, contrast summary, deployment rules), making it distinct from siblings like palette_generate 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?

No guidance on when to use this tool vs alternatives. With many colour/ palette siblings, the description should indicate scenarios like 'evaluate a set of colors' rather than single-color analysis or palette 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 indicate readOnlyHint=true, so no side effects. Description adds valuable behavioral context about the nature of comparisons (perceptual, semantic, cultural) and specific metrics calculated, surpassing baseline but not critical since read-only is annotated.

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

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

Two efficient sentences: first describes functionality, second provides usage boundaries. No unnecessary words, front-loads key information.

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

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

Given tool complexity (perceptual metrics, cultural context), description covers all relevant aspects. Output schema exists to document return values, so no additional return details needed.

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

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

Schema already covers both parameters with descriptions and examples (100% coverage). Description does not add new parameter-level detail, meeting baseline but not improving it.

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

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

The description clearly states the verb (compare), resource (two hex values), and specific outputs (LRV, chroma, hue angle, etc.). It explicitly distinguishes from sibling harmony tools, making the purpose unambiguous.

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

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

Explicit guidance: 'Use when choosing between two colours or explaining why one works better than another. Not a harmony tool.' This tells when to use and when not to, effectively differentiating 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?

Annotations already declare readOnlyHint=true, and the description's 'assess' aligns with a read-only operation. The description adds value by detailing what aspects of cultural risk are assessed (symbolic weight, regional taboos, etc.) and the scope (single colour or palette). No contradictions.

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

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

The description is extremely concise: two sentences that front-load the purpose and immediately provide usage guidance. Every sentence adds value, and there is no unnecessary information.

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

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

Given the presence of an output schema, 100% parameter coverage, and clear differentiation from 50+ siblings, the description covers all necessary context. It explains the tool's role relative to colour_passport and the scope of its function.

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

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

Schema coverage is 100% with clear descriptions for each parameter (hex, markets, palette). The description reiterates these but adds minimal new meaning, such as mentioning palette-level risk checks. Baseline 3 is appropriate as no additional semantic depth beyond the schema is provided.

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

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

The description clearly states the tool assesses cultural risk for a hex value or palette, covering symbolic weight, regional taboos, religious associations, and market flags. It explicitly differentiates from colour_passport, stating that this tool is one component of it and should be called directly for palette-level risk checks or when only cultural risk is needed.

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

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

The description explicitly states when to use this tool versus colour_passport: 'call this directly for palette-level risk checks or when cultural risk is the only thing being asked about.' It also explains that this is a component of colour_passport for single colours, providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by describing the output as a 'compact semantic fingerprint' and noting it is a component of colour_passport. No contradictions; adds context beyond the annotation.

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

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

The description is two sentences, front-loaded with purpose, and every sentence provides necessary information. No unnecessary words or repetition.

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

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

Given the simplicity of the tool (one parameter, read-only, with output schema), the description is complete. It states what it does, when to use it, and how it relates to other tools.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning about the 'hex' parameter beyond what the schema already provides ('Hex colour to fingerprint e.g. '#4A2A50'').

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: 'Compact semantic fingerprint for a single hex colour'. It also distinguishes from sibling 'colour_passport' by specifying that this tool is for the fingerprint format alone, while colour_passport is for a general colour profile.

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

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

Explicit usage guidance is provided: 'Use colour_passport for a general colour profile; use this only when the user explicitly wants the fingerprint format alone.' This clearly tells when to use this tool versus the alternative.

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

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

Annotations indicate read-only (readOnlyHint: true), and the description adds detailed behavioral context: returns verdict, risks, actions, light behaviour under three illuminants, substrate notes, alternative recommendation. No contradictions.

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

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

Concise one-paragraph with front-loaded purpose, summary of return values, methodology note, and concrete examples. Every sentence adds value.

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

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

Given the tool's complexity (5 params, 2 required, no enums, output schema assumed), the description covers purpose, return structure, and typical use cases thoroughly, making it self-sufficient for correct invocation.

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

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

Schema covers all parameters with descriptions, and the description adds real-world context (e.g., substrates like 'lime plaster', finishes like 'limewash', orientation examples), enhancing understanding beyond the schema.

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

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

The description uses a specific verb ('assess whether') and resource ('hex colour for physical application'), clearly distinguishing it from sibling colour tools like colour_cultural_risk or colour_match_paint.

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

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

The description does not explicitly state when to use this tool vs alternatives, nor when not to use it. Examples given are helpful but no comparative guidance with the many sibling tools.

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

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

Annotations already indicate readOnlyHint=true. Description adds that harmonies are matched to 'named archive colours', which is useful context. However, does not disclose limits, error handling, or behavior for unmatched colours.

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

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

Single sentence, front-loaded with key information. Every word is meaningful and there is no redundancy.

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

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

With output schema present and consistent annotations, the description is largely sufficient. It lacks detail on what 'named archive colours' are or how matching works, but overall it conveys the tool's core function adequately.

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

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

Schema covers both parameters (100% coverage). Description adds value by listing the four specific harmony types (complementary, triadic, analogous, split-complementary), which the schema's 'harmony_types' parameter does not enumerate. This helps the agent understand valid values beyond the 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?

Description clearly states it returns specific harmony types (complementary, triadic, analogous, split-complementary) based on a hex value, matched to archive colours. Distinct from sibling tools like 'colour_compare' or 'colour_combination'.

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

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

No explicit guidance on when to use this tool vs alternatives like 'colour_combination' or 'palette_generate'. The description implies its purpose but lacks context for 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?

Disclosures go beyond the readOnlyHint annotation: mentions backing by cultural provenance and tunability by audience and tone. No contradicting information; 'generate' is consistent with read-only 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?

Three sentences densely packed with information: output types, provenance backing, tunability, and use cases. No extraneous text, though a slight front-loading improvement could list outputs first more prominently.

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

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

Given the complexity of generating multiple content types and having an output schema, the description covers purpose, inputs, behavior, and use cases sufficiently. No major gaps identified.

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

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

Schema coverage is 100%, but description adds value by explaining parameters are 'tunable' and provides concrete examples of audience and tone values. This gives context beyond the schema's defaults and 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 specifies that the tool generates multiple outputs (hook sentence, story, tweet, image prompt, follow-up questions) for any hex colour, backed by archive colour cultural provenance. This clearly distinguishes it from sibling tools like colour_story or colour_namer that focus on single output types.

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

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

Explicitly states use cases: 'make archive colours shareable, generate content, or power a public-facing colour chat experience.' Provides clear context for when to use, though does not specify when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint=true, so the description adds minimal behavioral insight. It does not disclose how matches are computed, what happens with invalid inputs, or behavior when no match is found. The description relies on the annotation for safety disclosure.

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

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

A single sentence that clearly conveys the tool's function with no redundancy. Every word serves a purpose.

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

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

Given the tool's simplicity and the presence of an output schema, the description adequately covers the core functionality. It does not detail error handling or edge cases, but for a straightforward match tool this is acceptable.

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

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

Schema coverage is 100%, so the schema fully documents parameters. The description mentions brand names ('Farrow and Ball', 'Little Greene') which aligns with the schema's brand parameter, but adds no additional semantic value beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Find' and resource 'nearest named colour in commercial paint systems', clearly stating the tool's purpose. It explicitly names the brands (Farrow and Ball, Little Greene), distinguishing it from other colour-matching tools like colour_namer or colour_compare.

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

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

The description implies use when matching a hex value to named paint colours, but provides no explicit guidance on when to use this tool versus alternatives (e.g., colour_compare, colour_namer). No exclusions or when-not-to-use context is given.

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

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

Description lists specific metrics (LRV, chroma, hue angle, warmth, undertone) beyond the readOnlyHint annotation, giving clear behavioral insight. 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, front-loaded with key information, no extraneous words.

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

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

Fully adequate for low-complexity tool with complete schema, annotations, and output schema; description fills all needed context.

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

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

Schema covers hex_val with 100% coverage, but description adds context on output metrics, which aids understanding of parameter's purpose.

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

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

Description states specific verb 'returns' and resource 'raw perceptual metrics' for a single colour, and distinguishes from sibling tool 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?

Explicitly says when to use (user wants isolated numeric values) and when not to (use colour_passport for general profile), providing clear alternatives.

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

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

Annotations indicate readOnlyHint=true, and the description adds context about the CIE Lab subtractive model and perceptual accuracy, which goes beyond annotations. No destructive behavior is implied.

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 with no wasted words. It front-loads the purpose, then states outputs, and ends with an illustrative example. Perfectly concise.

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

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

For a tool with 3 parameters and an output schema (mentioned), the description covers the mixing model, return values, and example usage. It is complete for an AI agent to understand the tool's functionality.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by explaining the model (subtractive, CIE Lab) and giving an example that illustrates parameter usage. This provides semantic context beyond the schema.

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

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

The description clearly states it simulates subtractive mixing of two colours in CIE Lab space and returns the mixed hex value and nearest archive match. The verb 'simulate' and the example distinguish it from sibling tools like colour_compare or colour_combination.

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

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

The description implicitly tells when to use (for subtractive mixing with perceptual accuracy) and when not (not RGB screen blending). However, it does not explicitly mention alternative tools 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 value beyond the readOnlyHint annotation by explaining the generation is grounded in real archives and offers multiple styles. No contradiction with annotations; the security profile is consistently read-only.

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

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

Two sentences, front-loaded with the core action and key features. Every phrase 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 output schema exists (not shown but indicated), the description does not need to detail return values. It covers the tool's purpose, input scope, and use case adequately for a 5-parameter tool with rich annotations.

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

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

With 100% schema description coverage, the baseline is 3. The description lists the naming styles explicitly, which adds minor clarification over the style parameter's description, but does not significantly deepen understanding beyond the schema.

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

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

The description clearly states the tool generates archive-verified colour names from hex values, with specific naming styles and archive grounding. It effectively distinguishes from sibling tools like colour_story or ecommerce_namer by emphasizing the archive verification and product naming context.

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

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

The description implies use for Shopify product naming ('the core of the Shopify product naming use case'), but does not explicitly state when to avoid it or suggest alternatives among the many sibling tools. Clear context is provided, but exclusions are missing.

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

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

Annotations already declare readOnlyHint=true. The description adds context about the data returned but does not disclose additional behavioral traits like rate limits or authentication. It is consistent with annotations, so no contradiction.

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

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

The description is a single dense paragraph but effectively front-loads the purpose and lists return categories. It is appropriately sized given the tool's complexity, though a structured list could improve scannability.

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

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

With an output schema present, return values need not be explained. The description covers all key aspects: input parameters, output categories, batch capability, and relationship to siblings. It is complete for the tool's purpose.

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

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

Schema coverage is 100%, so parameters are well-documented in the schema. The description does not add significant meaning beyond what the schema provides, merely listing parameter names in context. Baseline 3 applies.

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

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

The description clearly identifies the tool as a 'Canonical single-call colour truth object' returning comprehensive data about a hex value. It distinguishes from siblings by explicitly stating it replaces chaining multiple tools (colour_dna, archive_provenance, etc.) and is the foundation call.

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

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

The description advises using this tool 'when you need the complete picture' and notes that 'every other tool is built on this data.' It implies when to use but does not explicitly exclude cases like when only a subset is needed, leaving alternatives 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?

Annotations indicate readOnlyHint=true, and the description adds transparency by detailing the returned fields (colour science, archive anchor, etc.) and the batch behavior (up to 20 hexes, deduplication). No contradictions.

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

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

Two sentences with no waste. Front-loaded with the key fact (batch version), then concisely covers limits, use cases, and output. Every sentence adds essential information.

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

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

Given the tool's complexity (4 parameters, output schema present), the description fully covers batch behavior, deduplication, use cases, and output summary. 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?

Schema coverage is 100%, but the description adds valuable context beyond schemas: batch limit of 20, deduplication, and a summary of output fields. This helps agents understand parameter impact and expected results.

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

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

The description clearly states it is the batch version of colour_passport, with a specific verb ('submit', 'returns') and resource (Colour Passport for hexes). It distinguishes itself from the sibling 'colour_passport' by emphasizing batch processing.

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 suggests use cases ('multi-colour workflows, Figma palette analysis') and when to avoid (calling individually for each colour would be slow). Also notes automatic deduplication, guiding efficient usage.

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

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

Annotations declare readOnlyHint=true, consistent with the description being a read operation. The description adds context about archive-grounded name source and dE2000 distance, which goes beyond the schema. No contradictions.

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

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

The description is short (two sentences) and front-loaded with the main purpose. The second sentence adds context but may be slightly cryptic; 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 tool's complexity (multiple token formats) and the presence of an output schema, the description sufficiently summarizes what the tool returns. The optional archive parameter is noted in context.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add significant meaning beyond the schema's field descriptions, maintaining 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 clearly states the tool returns developer token formats for a hex value, listing specific formats (CSS variable, kebab-case, camelCase, etc.). It distinguishes from sibling tools, none of which focus on token generation.

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

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

The description implies usage when needing token formats for a hex color, but does not explicitly state when to use this tool versus alternatives. No when-not or exclusion guidance is provided.

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

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

Annotations declare readOnlyHint=true, so the description accurately implies a read-only operation. It adds context about the output (narrative, history, meanings) but no additional behavioral details like error conditions or rate limits.

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

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

The description is concise (two sentences) with an example, front-loading the key purpose and usage contexts without unnecessary words.

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

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

Given the tool has only 2 parameters and an output schema, the description explains the output nature sufficiently. It could mention the return structure, but the output schema likely covers that.

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

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

Schema description coverage is 100%, with both parameters described in the schema. The description provides an example for hex but does not add significant semantic meaning beyond what is already 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's purpose: given a hex value, returns a rich narrative about the colour's cultural journey, history, meanings, and archive names. It distinguishes from siblings like colour_namer, colour_metrics, etc., which have different functions.

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

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

The description explicitly says it is essential for image generation prompts, brand storytelling, and creative briefs, providing clear use cases. However, it does not mention when not to use it or compare to similar siblings.

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

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

The description adds context beyond the readOnlyHint annotation by detailing what the tool combines and produces, enhancing transparency. It does not contradict annotations and provides behavioral insights into the tool's comprehensive analysis.

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

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

The description is well-structured and front-loaded with the purpose. It includes input/output lists and examples, though it is slightly lengthy. Every part adds value, earning its place.

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

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

Given the tool's complexity, excellent schema coverage, existence of output schema, and clear sibling differentiation, the description is complete. It covers purpose, inputs, outputs, examples, and usage context thoroughly.

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

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

The input schema has 100% coverage with detailed descriptions for all parameters. The description further elaborates by listing input components and providing concrete examples, adding meaning beyond the schema.

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

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

The description clearly states it's the 'flagship commercial endpoint' that combines multiple analyses, using specific verbs like 'combines' and listing all components. It distinguishes from siblings by implying this is the comprehensive tool while others are more focused.

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 positions this as the comprehensive tool with examples, but does not explicitly state when to use alternatives like the sibling tools. The usage context is clear but lacks explicit when-not-to-use guidance.

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

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

The description discloses the output: 'Returns a dated sequence of archive entries showing when and where the colour appeared, with primary sources.' This adds behavioral context beyond the readOnlyHint annotation, which only marks it as safe. The example further illustrates the range of data. No contradictions.

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

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

The description is three sentences plus an example, all front-loaded. Every sentence adds value: action, output, guidance, illustration. No wasted words or redundancy.

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

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

Given the tool's moderate complexity (two parameters, read-only, has output schema), the description covers what the tool does, what it returns, and when to use it. Since an output schema exists, the description does not need to detail return format. It is complete for an agent to decide 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?

The input schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds minimal extra semantics; the example ('indigo') gives a concrete concept but does not explain parameter syntax or constraints beyond what the schema provides.

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

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

The description clearly states the tool traces a colour concept or name across cultures and centuries in chronological order, which is a specific and unique action among siblings. It uses a strong verb ('traces') and defines the resource ('documented appearances'), distinguishing it from other colour tools like colour_story or colour_forensics.

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

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

The description explicitly states 'Use for historical research, provenance chains, and understanding why a colour carries the cultural weight it does,' providing clear context for when to use the tool. However, it does not explicitly exclude alternatives or mention when not to use it, so it's slightly less 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?

Annotations declare readOnlyHint=true, which the description aligns with by stating it 'return's data. The description adds context about what is returned (variants, lighter/darker, siblings) but does not disclose additional behavioral traits beyond the read-only nature, such as authentication requirements or rate limits. Since annotations already cover safety, the description provides marginal extra behavioral context.

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

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

The description is extremely concise with two sentences, no wasted words. It front-loads the core functionality and is well-structured.

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

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

The tool has an output schema, so return values are documented separately. The description explains the types of results (historical variants, lighter/darker, cultural siblings), which is sufficient for understanding. However, it lacks mention of prerequisites or edge cases, but this is acceptable given the simple parameters and annotations.

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 'name', which already describes it as 'Named archive colour e.g. Bourton Honey'. The description adds the phrase 'For any named archive colour' but does not significantly enhance meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states it returns historical variants, lighter/darker versions, archive matches, and cultural siblings for a given colour. It uses specific verbs and resources ('return historical variants, lighter and darker versions') and distinguishes itself from other colour tools like colour_harmonies or colour_compare by focusing on historical and cultural relationships.

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

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

The description says 'Essential for designers exploring around a colour,' which implies usage context but does not explicitly state when not to use it or provide alternatives among the many sibling tools. No guidance on when to choose this over other colour-related tools is given.

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 fully discloses the tool's behavior: it returns a verdict with strengths, risks, avoid-if scenarios, and alternatives. It also mentions the underlying methods (CIEDE2000, Claude cultural intelligence). This complements the readOnlyHint annotation perfectly.

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 (4 sentences) and front-loaded with the core purpose. Every sentence adds value, from the verdict types to the examples and the backing methods.

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

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

Given the presence of an output schema (implied by 'has output schema: true'), the description adequately explains the return structure. It covers all necessary aspects: verdict, strengths, risks, avoid-if, alternatives, and examples.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description adds value by providing real-world examples of how parameters are used (e.g., 'luxury hotel brand in Japan'), but does not add new semantic details beyond the schema.

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

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

The description clearly states it evaluates a hex colour for specific use case, market, and medium, and returns a decisive verdict. It distinguishes itself from sibling tools like 'colour_cultural_risk' by offering a broader evaluation including strengths, risks, and alternatives.

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

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

The description provides clear context on when to use this tool (evaluating a colour for a specific context) and gives compelling examples. However, it does not explicitly state when not to use it or compare directly to alternatives beyond implying the verdict-based output.

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

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

Annotations indicate readOnlyHint=true, and the description confirms it is a compound tool that returns a design package without side effects. It adds value by detailing the comprehensive output and that it replaces multiple calls, exceeding the annotation's minimal safety signal.

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

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

Three sentences, front-loaded with the core concept ('one-call compound tool'), followed by output details and usage guidance. Every sentence is informative and non-redundant.

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 as a compound tool with an existing output schema, the description fully covers its purpose, behavior, and usage context. No missing information for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific details beyond the schema; however, it contextualizes parameters by explaining the tool's compound purpose. No additional depth provided for individual params.

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

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

The description explicitly states it is a 'one-call compound tool' that replaces chaining multiple tools (query_conceptual, palette_from_concept, etc.), and specifies the output: a complete design package including palette, narrative, paint matches, accessibility check, and prompt. This clearly distinguishes it from sibling tools.

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

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

Describes when to use: 'when an AI agent or user needs a complete, deployable colour direction in a single call.' Also explicitly says 'Not for iterative refinement — use individual tools for that,' providing clear exclusions and alternatives.

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

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

The description explains that copy is grounded in archive provenance and colour names come from nearest match, and provides examples. With readOnlyHint already declared, this adds useful context without contradicting.

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 purpose and structured clearly. It is informative but slightly verbose for the amount of detail.

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

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

Given there is an output schema covering return values, the description covers all necessary context: inputs, output items, use cases, and provenance behavior. No gaps.

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

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

Schema coverage is 100% and schema descriptions are sufficient. The description summarizes inputs but does not add new semantic details beyond the schema.

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

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

The description clearly states it generates complete ecommerce product copy for any colour, listing inputs and outputs. It distinguishes from generic AI copy by emphasizing archive provenance.

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

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

The description mentions usefulness for Shopify, WooCommerce, and editorial product pages, but does not explicitly contrast with sibling tools like ecommerce_namer or colour_namer.

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

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

Annotations indicate readOnlyHint=true, and the description confirms a non-destructive operation. It adds valuable behavioral context: every name is 'archive-sourced, not invented' and carries a 'defensible' source citation. This goes beyond annotations by explaining the tool's principled approach.

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

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

The description is a single, well-structured paragraph. It front-loads the primary function and limit (40 SKUs), then covers inputs/outputs, unique selling points (archive-sourced), use cases, and style options. Every sentence adds 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?

Given the tool's complexity (5 parameters, output schema exists), the description is complete. It explains the tool's purpose, inputs, outputs, and application domains. The mention of output fields compensates for the unseen output schema, providing a clear mental model of 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?

Schema coverage is 100%, so baseline is 3. The description adds a narrative overview of inputs and outputs but does not significantly expand on schema descriptions. It lists style options and output fields, which is helpful but not transformative beyond the schema.

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

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

The description clearly states the tool's function: 'Generate archive-grounded colour names for up to 40 product SKUs.' It specifies inputs (hex values, product category, brand name, style) and outputs (archive name, source citation, etc.). It effectively distinguishes this from sibling tools like 'colour_namer' by focusing on product SKUs and archive-sourced names with citations.

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: 'Use for paint ranges, candle collections, fashion lines, homeware, cosmetics.' It also emphasizes that names are archive-sourced, guiding appropriate usage. While it doesn't explicitly state when not to use, the specificity of the listed domains provides clear context.

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

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

Annotations include readOnlyHint: true, which the description does not contradict. The description adds behavioral context beyond annotations by detailing the multi-step extraction and generation process. It does not mention rate limits or failure modes, but the overall transparency is good.

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

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

The description is a single paragraph that front-loads key information. It lists multiple outputs efficiently without redundancy. Minor improvement possible with bullet points, but it is appropriately concise.

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

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

The description covers the compound nature, key outputs, and usage hint. Given the complexity (8 parameters, optional) and the existence of an output schema, the description provides sufficient context for an AI agent to understand the tool's capabilities and when to use it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some value by mentioning style_context with examples and default values for k and model, but overall adds little beyond the schema descriptions.

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

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

The description clearly states it is a compound endpoint that takes one image and outputs a full creative brief, listing specific outputs (dominant colors, cultural naming, scene understanding, style period, product directions, prompt, swatch URL). It explicitly distinguishes from siblings by advising to use instead of chaining palette_extract + palette_analyse + agent_brief separately.

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

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

The description provides clear guidance on when to use the tool (as a compound alternative to chaining three separate tools) and mentions passing style_context for coherent archive matching. However, it does not explicitly state when not to use it or list alternative tools for partial tasks.

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

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

While annotations indicate readOnlyHint=true, the description adds behavioral details: the image is processed in memory only, uses K-means++ and Bradford chromatic adaptation, and returns up to 5 colours with specific attributes. No contradictions.

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

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

The description is two sentences, front-loading the main action and then detailing algorithm and output. It is concise and readable, though slightly dense.

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

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

Given the tool has an output schema, the description provides a comprehensive summary of functionality, privacy, and output details. It covers the essential context for a moderately 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 coverage is 100%, so the schema adequately documents parameters. The description adds value by summarizing the output (archive name, cultural story, RAL, WCAG), but does not enhance parameter meaning beyond the schema.

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

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

The description explicitly states the tool extracts dominant colours from an uploaded image and matches them to named archive entries with cultural provenance, clearly distinguishing it from sibling tools like palette_generate or colour_namer.

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

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

The description lists suitable use cases (product photography, interior photos, artwork, etc.) and notes the image is not stored, implying privacy. It lacks explicit 'do not use' conditions but provides enough context.

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

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

The description discloses that the photo is never stored (privacy), explains the use of Claude Vision and CIEDE2000 for analysis, and lists the output components. This adds significant value beyond the readOnlyHint annotation, which already signals safety.

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 approximately 80 words, front-loaded with the main purpose, followed by technical details and an illustrative example. Every sentence adds value; 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, the description does not need to detail return structure, but it already covers the key outputs (seasonal type, depth, undertone, palette, avoid colours) and the methodology. Context is fully sufficient for an agent to understand the tool's purpose and behavior.

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

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

Schema coverage is 100% with individual parameter descriptions. The tool description provides overall context but does not add per-parameter details beyond what the schema already offers. 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 uses specific verbs ('Upload', 'receive') and clearly enumerates the outputs (seasonal type, colour depth, undertone, curated palette with provenance, colours to avoid). The example solidifies understanding. Differentiates from siblings by focusing on personal analysis from a portrait photo, though not explicitly naming alternatives.

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

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

The description implies usage for personal colour analysis from a portrait photo, but does not explicitly state when to use this tool versus alternatives like image_palette or palette_generate. No exclusion criteria or prerequisites are mentioned.

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

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

Description adds value beyond readOnlyHint annotation by specifying exact input fields and output structure (resonance score, material origin, social function, alignment reason, confidence). Does not contradict annotations. Provides context that this is a proprietary metric with underlying scoring logic.

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?

Well-structured: purpose, explanation with examples, input/output format, use cases. Some redundancy (repeats 'proprietary metric' at start and end). Could trim but overall efficient and front-loaded with critical information.

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

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

Covers purpose, scoring logic, input format, output fields, and use cases. Output schema exists to detail return values. Minor issue: description implies all entry fields are required whereas schema only requires entries array. Otherwise complete for agent 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?

With 100% schema coverage, description adds meaning by elaborating on entries parameter (listing fields name, hex, archive, source, notes) and explaining default scoring basis from description context. Example score values (1.00, 0.80, 0.50) help interpret output but don't directly explain score_basis 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?

Description clearly states tool's purpose: scoring alignment between material origin and social consequence. Uses specific verb 'score', identifies resource 'colour entries', and provides examples of score values (1.00, 0.80, 0.50) to illustrate the metric. Distinguishes from siblings by emphasizing it's a proprietary Colour Memory metric.

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 lists use cases: investigative reports, forensic briefs, museum content, editorial PDFs. Also contrasts with palette generators, implying when not to use. However, no explicit alternatives among sibling tools or when-not-to-use conditions.

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

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

Annotations indicate readOnlyHint=false, so agents understand it's a write operation. Description discloses ephemeral processing, short-lived image_id (5 minutes), and upload behavior. Adds value beyond annotations.

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

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

Three sentences, front-loaded with action and return value. Every sentence adds value. 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?

Description covers tool purpose, key output (image_id with expiration), and integration points with downstream tools. Given existence of output schema, no further details are needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions a 50 KB size condition but does not provide additional parameter-level detail beyond what is already 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?

Clearly states the tool uploads an image to Colour Memory for ephemeral processing, returns image_id with 5-minute validity, and directs to downstream tools palette_extract or image_brief. Distinguishes itself from siblings by specifying usage for images over 50 KB.

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?

Specifies when to use the tool ('for any image over 50 KB') and mentions related tools. However, it does not explicitly state when not to use it or discuss alternatives for smaller images, though the schema reference to palette_extract's size limit provides some context.

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

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

Annotations declare readOnlyHint true, and the description confirms non-destructive generation. The description adds behavioral context about outputs (light behaviour, WCAG accessibility) but does not mention any side effects or dependencies, which is acceptable given 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 thorough but slightly long. It front-loads the main purpose and uses examples effectively. Every sentence adds value, though some redundancy exists (e.g., repeating 'bold maximalist living room' in examples).

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 existence of an output schema, the description is complete: it covers inputs, outputs (colour scheme, assignments, etc.), and mentions the PDF variant. No gaps 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?

All 6 parameters have schema descriptions (100% coverage). The description adds context on how parameters like style and orientation affect outputs (light advice), going beyond the schema. However, it does not add entirely new meaning for each 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 generates a complete interior colour specification from a concept or brief, listing specific outputs like 60/30/10 assignments, paint matches, and light behaviour. Examples and the distinction from the PDF tool show clear differentiation from sibling tools.

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

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

The description provides clear context on when to use (input concept, type, style), but does not explicitly state when not to use or name alternative tools. It does mention the PDF variant, offering some guidance.

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

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

Beyond the `readOnlyHint` annotation, the description adds deterministic behavior and no LLM cost, which are valuable traits. It also details the return structure (tool count, endpoint list, etc.), providing sufficient behavioral context.

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

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

The description is three sentences with no wasted words. The most critical information (what it does and when to use it) is front-loaded. Every sentence adds value.

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

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

For a tool with no parameters and an output schema, the description covers the key outputs and purpose. It could be slightly more complete by explicitly listing the output schema fields, but the provided details are sufficient for an agent to understand its role.

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

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

With zero parameters, the baseline is 4. The description correctly implies no input is needed, though it could explicitly state that the tool takes no arguments. However, no additional parameter clarification is necessary.

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

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

The description clearly states it returns a 'live inventory of all active endpoints and MCP tools', distinguishing it from sibling tools which are specific endpoints. The verb 'Return' and resource 'inventory' are specific and 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?

It explicitly recommends using this tool first to discover capabilities ('Use this first to discover what the API can do'). While it doesn't list exclusions or alternatives, the context makes it obvious this is the discovery tool among many specific tools.

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

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

Annotations already declare readOnlyHint=true, confirming no side effects. The description adds behavioral details such as palette-level deduplication, claim_strength rating, and do_not_say guardrails, going beyond annotations.

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

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

The description is two efficient sentences. It front-loads the core function and ends with a usage note. Every sentence adds value, though the first sentence could be slightly more broken down for readability.

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

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

Given the presence of an output schema and readOnly annotation, the description sufficiently covers the tool's behavior and usage context. It mentions deduplication and guardrails, which are important but not required 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%, so the input schema fully documents parameters. The description does not add meaning beyond what the schema provides, but it contextualizes the overall purpose, which indirectly aids parameter understanding.

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

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

The description clearly states the tool analyzes a palette of hex colours against the Colour Memory archive, returning specific data like cultural name, source, and claim_strength. It explicitly distinguishes from other palette tools by focusing on archival analysis and providing guardrails.

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 includes a direct usage guideline: 'Use after extracting colours from a photo or generating a palette.' This gives clear context but does not explicitly state when not to use or mention alternatives, though the sibling list provides 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?

Adds behavioral traits beyond annotations: deterministic, no LLM cost, and specific scoring dimensions. Annotations only provide readOnlyHint; description enriches with deterministic and cost-free nature.

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

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

Three sentences, front-loaded with core purpose, output details, and usage context. No wasted words.

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

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

Given the tool's complexity (4 params, output schema exists), description adequately covers input, process, and output. The deterministic and cost-free notes add valuable context.

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

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

Description does not elaborate on individual parameters. Since schema coverage is 100% with each parameter having a description, baseline 3 is appropriate. No added value beyond schema.

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

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

Description clearly states it's a full palette quality audit scoring multiple dimensions like accessibility and cultural risk, with specific output. It distinguishes itself from siblings by positioning as an enterprise gate before shipping.

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

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

Explicitly states 'use before shipping any palette', providing clear context. Does not mention alternative tools for specific sub-checks, but effectively guides when to use.

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

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

The description adds behavioral context beyond the readOnlyHint annotation by detailing the depth of analysis (perceptual, cultural, commercial) and the specific outputs returned. However, it doesn't disclose error handling or rate limits, though annotations cover the read-only nature.

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

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

A single well-structured sentence that front-loads the core purpose and lists key outputs. No unnecessary words, every part 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 moderate complexity, 4 well-described parameters, and an output schema, the description provides sufficient context for an agent to understand inputs and outputs. It mentions the return values (scores and verdict) without needing to detail the schema.

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

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

Schema covers all 4 parameters with descriptions, so baseline is 3. The description explicitly ties the use_case parameter to the verdict output, adding semantic meaning beyond the schema's static description.

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