Colour Memory

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

Annotations already declare readOnlyHint=true, and the description adds behavioral context by specifying the tool returns contrast ratios and pass/fail grades. This is consistent and informative, though additional details like rate limits or response size could improve it.

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

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

The description is a single concise sentence (18 words) that effectively front-loads the key purpose. No extraneous information is included.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 2 simple parameters and no output schema, the description adequately covers input and output. It specifies WCAG 2.1 version and that grades are AA/AAA, which is sufficient for selection.

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

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

Schema coverage is 100% but the description adds value by clarifying that 'hex_val' is the foreground hex and 'background' defaults to 'FFFFFF'. It reinforces the relationship between parameters beyond the schema labels.

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 WCAG 2.1 contrast ratios and AA/AAA pass/fail grades for a foreground hex against a background. This distinguishes it from sibling tools like get_colour_card or query_hex by specifying the accessibility focus.

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 WCAG accessibility checking but does not explicitly state when to use this tool versus alternatives. No exclusions or context for when not to use it are provided.

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

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

It discloses the algorithm (K-means++, Bradford adaptation), the return structure (up to 5 colours with archive name, cultural story, RAL, WCAG), and a critical privacy behavior (image processed in memory, never stored), all beyond the readOnlyHint annotation.

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

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

The description is concise with every sentence adding value: main action, method, output, use cases, and privacy. No redundant or irrelevant information.

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

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

Given the output schema exists, the description adequately covers the tool's purpose, behavior, and return values. It lacks explicit error handling or size limits, but overall is complete for an image palette extraction tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context (base64 encoding, default 5 colours, archive matching) but does not provide new meaning beyond what the schema already defines.

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

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

The description clearly states that the tool extracts dominant colour palettes from an uploaded image and matches them to named archive entries with cultural provenance, distinguishing it from siblings like 'mix_colours' or 'get_colour_card'.

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

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

The description provides explicit use cases (product photography, interior photos, etc.) and mentions privacy (image never stored), but does not explicitly state when not to use or offer alternatives among the 17 sibling tools.

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

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

Annotations already provide readOnlyHint=true, indicating a safe read operation. The description adds value by listing the exact data returned (colour count, embedding model, etc.), but it does not disclose additional behavioral traits like real-time constraints, caching, or rate limits. With annotations covering safety, a score of 3 is appropriate.

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

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

A single, front-loaded sentence that includes all key information without any fluff. Every phrase earns its place, listing the status components compactly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 no parameters and an output schema is present, the description fully covers what the tool does. It lists all return fields and the purpose. Complexity is low, and the description is sufficient for an agent to correctly invoke and understand the result.

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

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

The tool has zero parameters, and schema description coverage is 100% (trivially). Baseline for 0 parameters is 4. The description adds meaning beyond the empty schema by detailing what the return value contains, effectively acting as output documentation.

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 starts with 'Return live archive status', a clear verb+resource combination. It lists specific data fields (total colour count, per-archive breakdown, etc.), making the tool's purpose unambiguous. The tool has no siblings with similar functionality, so it is easily distinguishable.

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-to-avoid guidance is provided. However, the description implies this is a health-check or status tool, distinct from the color-focused siblings. Usage context is clear, but no alternatives or exclusions are mentioned.

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

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

Annotations already declare readOnlyHint=true. Description adds behavioral content (returns narrative, history, meanings, archive names) but does not address error handling or limitations like unsupported hex formats.

Agents need to know what a tool does to the 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 focused sentences plus a concrete example. Front-loaded with action and output description. 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 an output schema present, description does not need to detail return structure. It adequately describes the narrative content. Could benefit from clarifying distinction from 'colour_timeline' sibling, but not a major gap.

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

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

Schema has 100% coverage for both parameters. Description adds example for hex but no additional meaning for n_archives beyond what schema provides. 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?

Description clearly states it returns a cultural narrative about a colour given a hex value, with example output. However, it does not distinguish from sibling tools like 'colour_timeline', which may also return historical information.

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 context: 'Essential for image generation prompts, brand storytelling, and creative briefs.' But does not mention when not to use or offer alternatives, leaving the agent without explicit 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 declare readOnlyHint=true, consistent with the reading-only operation. The description adds behavioral details: chronological order, tracing across cultures and centuries, and example output. 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?

Three sentences plus an example, with the purpose stated upfront. Every sentence adds value: purpose, method, use case, example. No redundancy.

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

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

Given the tool's low complexity (2 params, annotations present, output schema exists), the description covers all necessary aspects: input, behavior, output, and context. It is complete for effective agent use.

Complex tools with many parameters or behaviors need more documentation. 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 mentions 'hex value' and implies tolerance through the example but does not add significant meaning beyond the schema's parameter 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 that the tool traces a colour's appearances across cultures and centuries in chronological order, using a specific verb ('traces') and resource ('colour's history'). This distinguishes it from siblings like 'colour_story' or 'query_hex'.

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 context on when to use the tool ('Essential for understanding why a colour carries the weight it does') and includes a concrete example, but does not explicitly mention when not to use it or compare with similar 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?

Given the readOnlyHint annotation already indicates this is a safe read operation, the description adds meaningful behavioral context by detailing the specific comparative dimensions (cultural context, stability under illuminants, historical signification) while remaining consistent with the annotation.

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

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

The description is two sentences long, front-loading the purpose and outputs in the first sentence, and providing usage context and exclusions in the second. Every sentence contributes value with no wasted words.

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

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

Given the presence of an output schema (as indicated by context signals), the description sufficiently covers the tool's purpose, inputs, and behavioral aspects without needing to detail return values. It provides a complete picture for an agent to decide on invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters adequately. The description mentions 'hex values' but does not add significant meaning beyond 'hex_a' and 'hex_b' as described in the schema, thus meeting 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 it performs a deep perceptual and semantic comparison between two hex values, listing specific outputs (LRV, chroma, hue angle, etc.) and distinguishing itself from sibling tools like harmony tools with the explicit statement 'Not a harmony tool — this is a decision and reasoning tool.'

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

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

The description explicitly says when to use it ('Use when choosing between two colours or explaining why one works better than another') and what it is not ('Not a harmony tool'), providing clear guidance on appropriate context 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?

Annotations provide readOnlyHint=true, and the description aligns by describing a read-only scoring operation. It adds behavioral context beyond annotations, such as returning warnings, positive associations, and market-specific flags, and notes that it is based on documented associations not generalizations.

Agents need to know what a tool does to the 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 (three sentences) and front-loaded with the core action. Every sentence contributes useful information without 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?

For a tool with three optional parameters, full schema coverage, an output schema, and clear annotations, the description provides sufficient context: what it does, what it returns (warnings, associations, flags), and when to use it. No gaps are evident.

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

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

Input schema has 100% description coverage, providing clear parameter details. The description adds minimal extra value by mentioning 'hex value or palette' and 'market flags', but overall 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 the tool assesses cultural sensitivity, symbolic weight, regional taboos, religious associations, and misinterpretation for a hex value or palette. It uses specific verbs and resources, and distinguishes from sibling tools like colour_story or query_conceptual by focusing on risk assessment.

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

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

Explicitly advises using the tool before deploying colour in global brand, product, or campaign contexts. While it does not list alternative tools or when not to use, the context is clear and actionable for an AI 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?

Annotations already provide readOnlyHint=true, so the safety profile is known. Description adds valuable context: it's a compound tool that replaces chaining multiple tools and returns a comprehensive output. No contradictions or hidden behaviors.

Agents need to know what a tool does to the 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 'One-call compound tool'. Efficiently describes inputs, outputs, and usage context. 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?

Given the tool's complexity as a compound tool, the description is thorough: lists all output components (palette, narrative, matches, accessibility, illuminant behavior, prompt). References replacement of 7 individual tools. Output schema exists, so return values are covered.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description mentions concept, medium, audience, and constraints but doesn't add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states it's a one-call compound tool that takes a concept and returns a complete design package. It lists the output components and explicitly distinguishes from sibling tools by naming alternatives like query_conceptual and palette_from_concept.

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

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

Explicitly states when to use: when a complete, deployable color direction is needed in a single call. Also states when not to use: not for iterative refinement, and directs to individual tools for that purpose. Naming specific sibling tools as alternatives provides 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?

The description discloses that the tool returns specific fields (hex, archive, provenance, cultural notes), adding value beyond the readOnlyHint annotation. However, it does not cover potential errors (e.g., unknown colour), authorization requirements, or format details.

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

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

The description is a single sentence that conveys the essential action and return information without any superfluous words. It is front-loaded and effective.

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

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

Given no output schema, the description provides a reasonably complete picture by listing the return fields. It lacks potential error scenarios or behavioural details but is adequate for a simple lookup tool with good annotations and schema coverage.

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

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

The input schema covers 100% of the single parameter with a description and examples, so the description adds only marginal meaning ('Look up a named colour'). The description does not clarify format constraints or case sensitivity beyond the schema, resulting in a baseline score.

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

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

The description clearly states the tool looks up a named colour and returns hex, archive, provenance, and cultural notes. It uses a specific verb-resource combination, and the title reinforces lookup by name. The tool is distinguishable from siblings like get_harmonies or query_hex because it focuses on metadata for a single named colour.

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 one has a colour name and wants detailed metadata, but it does not explicitly state when to use it versus alternatives like query_hex or get_harmonies. No exclusion criteria or context for when not to use it 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 already declare readOnlyHint=true, so the safety profile is clear. The description adds value by detailing what metrics are returned (LRV, chroma, etc.) and under which illuminants (D65, F11, A), providing behavioral context beyond the annotation. There is no contradiction.

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

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

The description is a single sentence that efficiently conveys the purpose and outputs without any fluff or repetition. Every word is meaningful 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?

Given the tool is simple (one required parameter, read-only) and there is an output schema (not shown but present), the description is complete. It explains what the tool does and what it returns, enabling an agent to decide if this tool is appropriate for a colour metrics query.

Complex tools with many parameters or behaviors need more documentation. 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 the single parameter hex_val, with a clear example. The tool description does not add additional meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool returns perceptual colour metrics and lists specific metrics (LRV, chroma, hue angle, warmth classification, illuminant shifts). It identifies a specific resource and action, and distinguishes from siblings like get_colour_card or match_paint_system by focusing on perceptual properties.

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 provide explicit guidance on when to use this tool versus alternatives. While it implies usage for getting colour metrics, it lacks instructions on when not to use it or how it compares to other tools like analyse_image_palette or compare_colours. Given many siblings, this is a 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 the tool as read-only (readOnlyHint=true), and the description is consistent. No additional behavioral details are provided beyond the annotation.

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

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

Single sentence, no wasted words. Front-loads the key action and result. Very 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?

With no output schema, the description does not explain the return format, error handling, or behavior for invalid hex values. Lacks completeness for a 2-param 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 covers 100% of parameters with descriptions. The tool description does not add extra meaning beyond what the schema already provides.

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

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

The description clearly states the tool returns specific types of harmonies (complementary, triadic, analogous, split-complementary) matched to named archive colours, using accurate verbs and resource specification.

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 versus siblings like get_colour_card, query_hex, or specify_palette. The description only states functionality, not 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 fully details what the tool generates (colour scheme, assignments, provenance, paint matches, light behaviour, accessibility, rationale). While annotations indicate readOnlyHint=true (consistent with generation), the description adds substantial behavioral context, far exceeding annotation coverage.

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

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

The description is front-loaded with the main purpose and contains valuable examples. It is structured as one paragraph with clear steps. While somewhat lengthy, every sentence contributes meaning. Could be slightly more 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 complex tool generating multiple outputs, the description covers all key aspects: inputs, output components, examples, and alternative tool. Given that an output schema exists, the description is sufficiently complete for an agent to understand the tool's capabilities.

Complex tools with many parameters or behaviors need more documentation. 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, baseline is 3. The description provides example values for the concept parameter and overall context, but does not add significant meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool generates a complete interior colour specification from a concept or brief. It lists specific outputs like 60/30/10 assignments, paint matches, and light behaviour, and gives explicit examples. This distinguishes it from the sibling /interior-specification/pdf tool.

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

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

The description provides examples and mentions an alternative tool for PDF output. However, it does not explicitly differentiate itself from many siblings like palette_from_concept or specify_palette, nor does it specify when not to use this tool.

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

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

Description is consistent with readOnlyHint annotation, indicating a read operation. No additional behavioral details (e.g., what happens if no match found, result ordering) are given beyond what annotations and schema provide.

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

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

Description is a single sentence that is front-loaded with the action. It is concise and contains 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?

With an output schema present and schema coverage high, the description covers the core purpose but lacks details on edge cases or behavior. It is minimally adequate for the tool's complexity.

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

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

Schema coverage is 100%, with all parameters described adequately. The description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

Description clearly states the tool finds the nearest named colour in commercial paint systems, specifically naming Farrow and Ball and Little Greene. This provides a specific verb and resource, and distinguishes it from sibling tools like query_hex or get_harmonies.

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

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

No explicit guidance on when to use this tool versus alternatives like query_hex or colour_story. The mention of specific brands implies usage context, but no exclusion or when-not-to-use information 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 only provide readOnlyHint=true. Description adds details: perceptual model, CIE Lab space, returns hex and nearest archive match with cultural context. 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?

Concise, front-loaded with core concept, includes a concrete example. Every sentence is valuable.

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

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

Output schema exists, description mentions return values (mixed hex, archive match). Adequately covers behavior of a mixing tool with given complexity.

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

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

Schema coverage 100% but description adds value: explains subtractive model, perceptual accuracy, gives example (Prussian Blue + Yellow Ochre) 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?

Description clearly states it simulates subtractive mixing in CIE Lab space, not RGB blending, and gives a specific example. Distinguishes from sibling tools like compare_colours and simulate_colour_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?

States 'not RGB screen blending' hinting at when not to use. Context of sibling tools makes usage clear, though explicit when-to-use vs alternatives could be tighter.

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 value beyond readOnlyHint annotation by specifying that colors are 'sourced from the archive with documented history'. Minor inconsistency: description says 4-6 colors, but parameter allows up to 8.

Agents need to know what a tool does to the 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 clear sentences plus a list of examples. Every sentence adds value, but the structure could be more explicit about output or usage. 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 3 parameters, output schema exists, and tool is read-only, the description covers purpose, provenance, and typical use cases. Could mention that tool returns historical colors only, but lacks guidance on invalid concepts.

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

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

Schema coverage is 100%, so baseline is 3. Description reinforces concept parameter with examples but adds little beyond schema. The number of colors mismatch (4-6 vs 5 default, max 8) slightly reduces clarity.

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

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

Clearly states verb (generate), resource (historically grounded colour palette), and source (cultural concept). Examples like 'Victorian mourning' distinguish it from sibling tools like query_conceptual or colour_story, which focus on different aspects.

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

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

Examples suggest appropriate use cases but no explicit when or when-not statements. No mention of alternatives among 18 sibling tools, leaving the agent uncertain about which tool to select for related needs.

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

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

Beyond readOnlyHint annotation, the description discloses use of Claude Vision, that the photo is never stored, and provides output details. Adds meaningful behavioral context without contradiction.

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

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

Description is three sentences plus an example, each sentence adds value. Front-loaded with purpose, then details, then example. 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 existence of an output schema, the description covers input, process, output, and example. Complete for an AI agent to understand usage.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant extra meaning beyond the schema; it mentions natural light which is already in the schema. No new parameter insights.

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 uploads a portrait photo and returns a personal colour analysis, specifying seasonal type, colour depth, undertone, and curated palette. It distinguishes from siblings like 'analyse_image_palette' by focusing on personal analysis from a portrait.

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 wanting a personal colour analysis from a portrait, but does not explicitly state when not to use it or mention alternative tools. No exclusions or context provided.

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

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

Annotations already declare readOnlyHint=true, so the description adds context that it returns 'named archive colours with provenance and cultural context', but does not disclose any additional behavioral traits like rate limits or return format limitations.

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

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

Two concise sentences, front-loaded with purpose. Every word adds value; no redundancy or unnecessary detail.

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

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

Given the absence of an output schema, the description adequately specifies the return type ('named archive colours with provenance and cultural context'). With 3 parameters fully documented in the schema and a readOnly annotation, the description covers most needs, though it could hint at result ordering or pagination.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema for any parameter. The phrase 'abstract queries' is about usage guidance, not parameter semantics.

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

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

The description explicitly states the tool's purpose with a specific verb ('Ask') and resource ('colour question'), and gives concrete examples of abstract queries like 'grief' or 'Ottoman luxury'. It clearly distinguishes from siblings by contrasting with query_hex (likely hex-based) and other 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 with 'Works for abstract queries' but does not explicitly state when not to use or mention alternative tools for other types of colour queries (e.g., hex). No exclusions or comparisons are provided.

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

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

Annotations declare readOnlyHint=true, but the description adds no further behavioral context beyond mentioning CIEDE2000. It does not disclose error handling, performance, or any side effects.

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

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

The description is a single concise sentence that is front-loaded with the core action and uniquely identifying detail (CIEDE2000). 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?

Given the simple tool with readOnlyHint, full schema, and no output schema, the description adequately states purpose but omits what the returned results contain (e.g., colour names, distances). Agents may need to infer format.

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

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

Schema coverage is 100% with clear descriptions for all three parameters (hex with example, archive as optional, n_results with default). The description adds no extra meaning beyond the schema.

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

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

The description clearly states the verb 'Find', the resource 'named archive colours', and the method 'using CIEDE2000 perceptual distance'. It distinguishes from siblings like query_conceptual which likely searches by name.

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 provide guidance on when to use this tool versus alternatives like query_conceptual, brand_match, or specify_palette. No exclusions or context for 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 already declare readOnlyHint=true, so description does not need to emphasize safety. It adds the specific model name but no extra context about edge cases or error handling.

Agents need to know what a tool does to the 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 that is concise, front-loaded with the key action, and contains no redundant 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?

For a simple tool with one parameter and read-only behavior, the description is largely complete. It could mention the output format (object with three keys) but is sufficient for an agent to use.

Complex tools with many parameters or behaviors need more documentation. 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 fully describes the parameter (hex_val with example). Description repeats the return type but adds no new semantic or constraint 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 returns simulated hex values for three specific types of colour blindness using a named model. It is distinct from sibling tools like accessibility_check or get_colour_card.

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

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

Description implies usage for colour simulation but provides no explicit guidance on when to use this tool versus siblings like accessibility_check, nor when not to use it.

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

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

Annotations declare readOnlyHint=true, and description confirms a read operation (returns specification). Adds specific behavioral details: requires 2-8 hex values, returns surface assignments, 60-30-10 proportions, lighting behaviour, and archive colour names.

Agents need to know what a tool does to the 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 short, front-loaded sentences with no unnecessary words. Every phrase 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?

Describes key outputs comprehensively. However, lacks explanation of how 'style' and 'room_type' influence the result, which would be helpful for an agent.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description reinforces that 'colours' must be 2-8 hex values but does not add significant new 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?

Clearly states 'Generate a complete interior specification' and lists outputs (surface assignments, proportions, lighting, archive names). Distinguishes from siblings like get_harmonies and get_colour_card which have different purposes.

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

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

Implied usage when you have 2-8 hex values and want a palette specification, but no explicit guidance on when to use this tool versus alternatives such as get_harmonies or get_colour_card.

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 behavioral traits: it accepts items, returns a verdict on clashes and missing colors, references historical archive colors, and suggests additions. The readOnlyHint annotation confirms no destructive actions, and the description aligns with this by describing a read-only advisory operation.

Agents need to know what a tool does to the 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 slightly verbose but well-structured: it opens with the core question, then explains inputs, outputs, and examples. Every sentence adds value, though a few words could be trimmed without loss of clarity.

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

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

Given the tool's complexity (three parameters, two optional), the description covers all necessary context: input format, optional fields, output contents (verdict, archive colors, missing item suggestions), and practical examples. An output schema exists but is not shown; the description compensates by detailing what the user can expect.

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

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

The description adds significant meaning beyond the schema: it explains that items must include a label (e.g., 'dress') and hex color, gives examples for the ask parameter, and clarifies the optional occasion field. Since schema coverage is 100% and the description enriches each parameter with real-world usage, it meets the highest standard.

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: it accepts outfit items as hex values with labels and returns a verdict on color compatibility. Examples like 'Does this bag go with this outfit?' and specific queries ('What shoes?') make the verb+resource explicit. It distinguishes from sibling tools like analyse_image_palette or colour_story, which focus on different color analysis tasks.

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

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

The description provides clear context for when to use this tool (fashion color matching) and includes examples of typical questions. However, it does not explicitly state when not to use it or mention alternative tools for related color queries, such as query_conceptual for general color advice.

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