Colour Memory

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

The description aligns with the readOnlyHint annotation, but it adds minimal behavioral context beyond what is already available. It discloses the return type but does not elaborate on safety, performance, or side effects, relying heavily on 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 consists of a single, well-structured sentence that efficiently conveys the tool's purpose without unnecessary verbiage.

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 (2 parameters, no output schema), the description adequately covers the inputs and outputs. It could briefly mention the return format or grading criteria, but it is largely complete for a focused utility.

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, the baseline is 3. The description adds value by reiterating that the foreground hex is compared against a background, but it does not significantly enhance understanding beyond the parameter descriptions already present 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 specifies the verb 'Return' and the resource 'WCAG 2.1 contrast ratios and AA/AAA pass/fail grades', along with the input parameters (foreground hex against a background). This distinguishes it from sibling tools like brand_match or get_harmonies, which serve different purposes.

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

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

The description makes it clear the tool is for checking WCAG accessibility, implying its usage. However, it does not provide guidance on when to avoid using it or compare it with alternative sibling tools, leaving room for potential misinterpretation.

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 adds technical details (K-means++, Bradford chromatic adaptation) and privacy assurance (image not stored). No contradictions; description enriches behavioral understanding.

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

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

Four sentences, each purposeful. First sentence summarizes core action and output. Subsequent sentences add technical and usage context concisely. No redundancy or filler.

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

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

Given the tool's complexity and the presence of an output schema, the description covers key aspects: input, processing method, output characteristics, use cases, and privacy. It is complete enough for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds no significant detail beyond what the schema already provides (e.g., defaults, MIME types). It restates some parameter descriptions, offering minimal extra value.

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 extracts dominant colours from an uploaded image and matches them to named archive entries. It specifies input format (base64) and output details (up to 5 colours with provenance). This distinguishes it from sibling tools like palette_from_concept or compare_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?

Description lists appropriate use cases (product photography, interior photos, artwork, brand assets, mood boards) and notes the image is processed in memory only. However, it does not explicitly mention when not to use or suggest alternative tools.

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

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

Annotations already declare readOnlyHint=true. The description adds value by listing the specific fields returned and the 'live' nature, which implies non-cached data. No contradictions. It provides additional behavioral 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, well-structured sentence that front-loads the purpose and lists key returns. 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?

For a tool with zero parameters and an existing output schema, the description covers all essential return fields. It is sufficiently complete for an agent to understand what the tool provides.

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 100% schema coverage. The baseline is 4 for such cases. The description does not need to add parameter information and appropriately focuses on the output.

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 'Return live archive status' with specific details (total colour count, per-archive breakdown, embedding model, search engine state, API version). It uses a specific verb and resource, and distinguishes itself from sibling tools which are analytical or design-oriented.

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

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

The description provides clear context for when to use the tool (to retrieve archive status), but does not explicitly mention when not to use or list alternative tools. Given the sibling tools are diverse, the implicit context is sufficient for appropriate 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?

Annotations already indicate readOnlyHint=true, and the description confirms a read operation (returns a narrative). No additional behavioral traits (e.g., error handling, rate limits) are disclosed beyond what annotations provide. The description adds the concept of 'archive names' but does not contradict 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 three well-structured sentences: the first defines the action, the second lists use cases, and the third provides an example. 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?

The tool has two parameters, an output schema, and annotations. The description covers the core functionality and use cases. It could mention validation of hex values, but overall it is sufficient given 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?

The input schema has 100% coverage for both parameters (hex and n_archives). The description only mentions hex in the example and does not add semantic value 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 the tool returns a cultural narrative for a colour given a hex value, with an explicit example. It distinguishes itself from sibling tools like colour_timeline and cultural_risk_assessment by focusing on the cultural journey and historical meanings.

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 specifies when to use the tool: for image generation prompts, brand storytelling, and creative briefs. However, it does not explicitly mention when not to use it or suggest alternative 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?

Describes the chronological ordering and historical scope, going beyond the readOnlyHint annotation to explain the nature of the output. Does not introduce any 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?

Four sentences with key information front-loaded: the action, the scope, the purpose, and a concrete example. No extraneous 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 presence of an output schema, the description adequately covers input, process, and value. The example illustrates typical usage, making it self-contained.

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

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

Both parameters are fully described in the input schema (100% coverage), so the description adds no additional meaning beyond reinforcing the hex 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?

Clearly states the tool traces a colour's appearances across cultures and centuries in chronological order. The example of deep blue reinforces the purpose and distinguishes it from siblings like colour_story or cultural_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?

States it is 'essential for understanding why a colour carries the weight it does', indicating when to use it for historical context. Does not explicitly exclude alternatives but provides clear contextual 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, which is consistent with the description's indication of a read-only comparison. The description adds behavioral detail about what is compared (LRV, chroma, hue, etc.) and notes that it is not destructive. 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 efficient, with four sentences that front-load the purpose, list key outputs, and give 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 output schema exists (implied by the detailed outputs mentioned), the description sufficiently covers purpose, usage, and behavioral traits. The tool has only 2 required parameters with 100% coverage, and no enums, so the description is complete.

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

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

Schema description coverage is 100%, with both parameters described as hex values. The description does not add additional semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs 'deep perceptual and semantic comparison between any two hex values' and lists specific outputs like LRV, chroma, hue angle, etc. It explicitly distinguishes from sibling tools by stating '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 provides explicit guidance: 'Use when choosing between two colours or explaining why one works better than another' and contrasts with harmony tools. This makes it clear when to use and when not to.

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 tool is safe. The description adds rich behavioral context: returns warnings, positive associations, context-dependent readings per colour family, and specific market flags. It also clarifies that assessments are based on documented associations, not generalizations, which is valuable 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 efficiently structured in three sentences, front-loading the main action and then providing specifics on returns and usage. 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 complexity (3 optional params, output schema exists), the description covers the core functionality, return types, and usage context. It does not detail output structure (handled by output schema) or edge cases, but is generally complete for an assessment tool.

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

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

Schema description coverage is 100% for all 3 parameters (hex, markets, palette). The description mentions 'hex value or palette' and 'market flags', but does not add significant detail beyond the schema descriptions. For example, it doesn't explain how markets filter results or the exact format of hex values. Baseline 3 is appropriate.

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

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

The description clearly states the tool scores a hex value or palette for cultural sensitivity, symbolic weight, regional taboos, religious associations, and potential misinterpretation. It distinguishes from sibling tools like accessibility_check or colour_story by focusing specifically on cultural risk assessment for global contexts.

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 deploying a colour in a global brand, product, or campaign context', providing clear when-to-use guidance. However, it does not mention when not to use or contrast with alternatives, though the sibling list implies differentiation.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. Description adds valuable behavioral context: it is a compound tool that replaces multiple calls and returns a package of results. 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?

Concise: two sentences plus usage guidance. Front-loaded with the most important fact ('One-call compound tool'). 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, the description covers the main points: inputs, outputs, and replaced tools. Output schema exists, so return values are documented. However, the input list in the description includes extraneous items (audience, constraints), which creates a minor completeness gap.

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

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

Schema coverage is 100% with descriptions for all 6 parameters, but the description mentions 'audience' and 'constraints' as inputs, which are not parameters in the schema. This inconsistency may confuse the agent about available inputs.

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 it is a 'one-call compound tool' that takes a concept and returns a complete design package. Distinguishes from siblings by naming the individual tools it replaces (e.g., query_conceptual, 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 says 'Use when an AI agent or user needs a complete, deployable colour direction in a single call' and 'Not for iterative refinement — use individual tools for that.' Provides clear when-to-use and 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 annotations already indicate readOnlyHint=true. The description adds value by listing the specific fields returned (hex, archive, provenance, cultural notes), providing behavioral context beyond what annotations offer.

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

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

The description is a single concise sentence that is front-loaded with the verb 'look up' and clearly specifies the resource (named colour) and output fields. No wasted words.

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

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

For a simple lookup tool with one parameter and no output schema, the description adequately explains what the tool returns. However, it could be slightly improved by clarifying that the lookup is case-sensitive or requires exact name formatting.

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

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

Schema coverage is 100% and the parameter description includes examples. The description does not add new semantic information about the parameter beyond what the schema provides, so baseline 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 looks up a named colour and returns specific details (hex, archive, provenance, cultural notes). This distinguishes it from siblings like query_hex which likely queries by hex value.

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 you have a colour name, but does not explicitly state when not to use this tool or mention alternatives. Sibling tools exist (e.g., query_hex) but no comparative 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?

The readOnlyHint annotation already indicates the tool is safe and non-destructive. The description does not contradict this and adds no additional behavioral traits (e.g., rate limits, permissions). It is consistent but does not exceed the annotation.

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

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

The description is a single, well-structured sentence that immediately conveys the tool's purpose and outputs. There is no wasted text, and it is front-loaded with the key action.

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

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

The description provides a good overview of the output metrics, and the presence of an output schema (confirmed by context signals) reduces the need to explain return values. However, it could be more complete by mentioning whether multiple values are accepted or how errors are handled.

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 for a single parameter 'hex_val', which is clearly described. The description does not add extra meaning for the parameter itself; it focuses on the output metrics. Baseline score is appropriate as the schema already covers the parameter.

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

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

The description clearly states it returns perceptual colour metrics and lists specific examples (LRV, chroma, hue angle, etc.). It uses a specific verb ('Return') and resource, but does not explicitly differentiate from sibling tools such as 'get_colour_card' or 'compare_colours', which may also return colour 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?

No guidance is provided on when to use this tool versus alternatives. The description only lists what the tool returns, without specifying context, prerequisites, or exclusions. Among 17 sibling tools, no differentiation is offered.

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 by explaining that harmonies are matched to named archive colours, implying a lookup behavior. It does not disclose edge cases (e.g., missing hex) but provides useful behavioral 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 a single sentence of 12 words, front-loading the key action and output. Every word is informative with no redundancy or filler, making it highly efficient.

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

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

For a simple read tool with two parameters and no output schema, the description is fairly complete. It names the output types and the matching behavior. However, it could be improved by briefly noting the format of the returned data (e.g., array of color objects).

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by listing the concrete harmony types ('complementary, triadic, analogous, and split-complementary'), which are not specified as enums in the schema, thus clarifying valid values for harmony_types.

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 'harmonies', listing specific types (complementary, triadic, analogous, split-complementary). It distinguishes from sibling tools like get_colour_card and query_hex, which serve different purposes.

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

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

No usage guidelines are provided. The description does not specify when to use this tool versus alternatives, nor does it mention any prerequisites or limitations. Sibling tools like get_colour_card and query_hex are listed but not compared.

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 consistently describes a read-only generation operation. The description elaborates on the detailed outputs, including paint matches, light behaviour, and accessibility, which adds significant transparency beyond the annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose. It includes examples, references to an alternative tool, and a clear statement of scope. Every sentence adds value with 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 complexity and the presence of an output schema, the description covers all necessary elements: generation scope, output components, and usage examples. It provides sufficient context for an agent to decide when and how to invoke it.

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

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

The input schema covers all parameters with clear descriptions (100% coverage). The description reinforces the meaning of 'concept' with examples but does not add new semantic details beyond the schema. The examples provide useful illustration, so a slight improvement over 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 generates a complete interior colour specification from a concept or brief. It lists specific outputs like 60/30/10 surface assignments, paint matches, light behaviour, and cultural rationale. The examples and mention of a PDF alternative help distinguish it from siblings like palette_from_concept or specify_palette.

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 usage context by saying it replaces a colour consultation and gives example inputs (e.g., 'bold maximalist living room'). It also mentions the PDF tool for downloadable output. However, it does not explicitly state when not to use it or which sibling alternatives are better suited for simpler needs.

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

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

Annotations already provide readOnlyHint=true, so the description aligns. However, the description adds no additional behavioral context beyond the action of finding colours, such as response details or limitations. The bar is lowered by annotations, but the description is minimal in this regard.

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 is front-loaded with the core action and includes key examples of paint systems. No wasted words; 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 the presence of an output schema, the description adequately covers the tool's purpose and available brand filter. It does not explain the output shape, but that is handled by the output schema. Minor gap: could hint at the number of matches parameter.

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 itself documents parameters well. The description adds no extra semantics beyond confirming brand filter behavior. Baseline score of 3 is appropriate.

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

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

The description explicitly states 'Find the nearest named colour in commercial paint systems including Farrow and Ball and Little Greene,' which clearly identifies the action and resource. It distinguishes from sibling tools like query_hex or get_colour_card by specifying commercial paint 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 implies when to use the tool (to find commercial paint matches) and includes an optional brand filter, but lacks explicit directives on when not to use it or alternatives. The context is clear but without 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, and description reinforces that it's a simulation (not destructive). It adds details about the subtractive model in CIE Lab space and perceptual accuracy, providing context beyond annotations. 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?

Description is three sentences: first sentence states purpose, second adds technical detail, third provides an example. No redundant information, front-loaded, and efficient.

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

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

Description explains the model, output (hex plus nearest archive match with cultural context), and gives an example without requiring output schema. It lacks details on error handling or edge cases, but is sufficient for a simulation tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds an example (Prussian Blue and Yellow Ochre) that contextualizes the mix, but does not significantly enhance the meaning of parameters beyond the schema.

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

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

Description clearly states the tool simulates perceptually modelled subtractive mixing of two colors in CIE Lab space, returning a hex value and nearest archive match. It distinguishes from siblings by noting it's not RGB screen blending, and provides an example that clarifies 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?

Description implies usage for mixing two colors perceptually, but does not explicitly state when to use this tool over siblings like compare_colours or simulate_colour_blindness. No exclusions or alternative tools mentioned, though the specificity provides 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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds value by specifying that every colour is 'sourced from the archive with documented history,' providing provenance context beyond what annotations convey. No side effects or destructive actions are implied, consistent with the read-only annotation.

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

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

The description is two concise sentences plus examples, front-loading the action ('Generate...palette') and key output details. Every sentence provides meaningful information with no redundancy or fluff.

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

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

Given the existence of an output schema, the description need not detail return structure. It adequately covers output content (hex, proportions, provenance) and provides examples of valid concepts. However, it does not address edge cases like unsupported concepts or error handling, leaving minor gaps 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 all parameters are already described. The description does not repeat parameter details but mentions '4-6 colours' while the schema allows n_colours up to 8, creating a slight mismatch that could mislead agents about the range. The examples help clarify the concept parameter, but overall the description adds minimal new 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 uses a specific verb ('Generate') and resource ('Heritage Palette from Cultural Concept'), clearly stating the output (4-6 colours with hex, proportions, provenance). Examples like 'Victorian mourning' and 'Japanese wabi-sabi' provide concrete context, effectively distinguishing this from sibling tools that might return single colours or raw data.

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

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

The description implicitly suggests use for historical or cultural colour synthesis through examples, but does not explicitly state when to use this tool over alternatives like query_conceptual or design_session. No exclusions or alternatives are mentioned, making usage guidance only 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?

Discloses key behaviors beyond annotations: uses Claude Vision, photo never stored, matches by CIEDE2000. Annotations only state readOnlyHint=true; description adds privacy and processing 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?

Front-loaded with purpose, structured logically: input, process, output. Every sentence adds value without redundancy. Concisely conveys a complex tool.

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

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

Given complexity and presence of output schema, description fully covers inputs, process, outputs, and nuances like CIEDE2000 and example. Leaves no gaps for an AI 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%, so baseline is 3. Description adds extra guidance like 'Face should be clearly visible in natural light' and explains optional name, improving usability.

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 specifies verb 'upload' and resource 'portrait photo', and distinct output: seasonal type, depth, undertone, curated palette. Distinguishes from siblings like 'analyse_image_palette' by focusing on personal analysis with photo.

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

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

Provides clear context for when to use (upload portrait photo) and an example, but does not explicitly state when not to use or mention sibling tools as alternatives.

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

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

The description adds value beyond the readOnlyHint annotation by specifying that results include provenance and cultural context. It does not contradict annotations and provides useful 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 concise (three sentences), front-loaded with the core purpose, and every sentence adds value with examples and clarification.

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

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

For a read-only search tool with no output schema, the description adequately explains the return type ('named archive colours with provenance and cultural context'). It covers the essential aspects for the 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?

All three parameters have descriptions in the schema (100% coverage), so baseline is 3. The description does not add significant additional meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Ask') and resource ('colour question'), clearly states it returns named archive colours with provenance and cultural context, and differentiates from sibling tools like 'query_hex' by emphasizing conceptual/cultural queries.

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

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

The description provides clear context for when to use the tool (cultural, historical, material colour questions) with concrete examples, but does not explicitly state when not to use or mention alternatives.

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

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

Annotations declare readOnlyHint=true, so the tool is safe. The description adds valuable behavioral context: it uses CIEDE2000 distance and returns closest matches, not exact ones. This goes 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, well-structured sentence that conveys the essential purpose and method without redundancy. It is front-loaded and efficient.

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

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

No output schema exists, but the description does not specify the structure of the response (e.g., list of colour names, distances, hex codes). The algorithm is mentioned, but return format is missing, leaving the agent partially uninformed.

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, with each parameter documented. The description does not add extra parameter information beyond what the schema provides, so it meets the baseline without adding value.

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 finds the closest named colours to a hex value using CIEDE2000 distance. It specifies the resource (named archive colours), the action (find closest), and the method (perceptual distance), distinguishing it from siblings like query_conceptual 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 implies the tool is for hex-based colour matching, but lacks explicit guidance on when to use it versus alternatives (e.g., query_conceptual). No when-not-to-use or prerequisite 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 already declare readOnlyHint=true, so the tool is safe. The description adds the specific model used and the exact types of color blindness simulated, which is beyond what annotations provide. However, it does not mention error handling for invalid hex values.

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 tool's purpose and methodology. 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 (1 parameter, no output schema), the description covers the core functionality well. However, it does not specify the output format (e.g., whether it returns a single hex or an object with keys for each condition), which would be helpful for an agent to interpret results.

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

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

Schema coverage is 100% with a clear description and example for the single parameter hex_val. The tool description adds no additional parameter semantics beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns simulated hex values for three types of colour blindness using a specific model (Brettel-Vienot-Mollon). It distinguishes from sibling tools like 'query_hex' which likely return standard color info, and 'accessibility_check' which may be broader.

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 needs simulated color blindness effects, but lacks explicit guidance on when to use this tool versus alternatives like 'accessibility_check'. No exclusions 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?

Annotations declare readOnlyHint: true, and the description aligns by describing a generation operation. The description adds value beyond annotations by detailing what the returned specification includes (surface assignments, proportions, lighting, archive 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?

The description is a single, information-dense sentence that front-loads the action and input constraints. Every piece of information is necessary and well-structured.

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

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

For a tool with 3 parameters, no output schema, and no nested objects, the description covers the core functionality and output. It lacks error handling or edge case info, but these are often implicit. The description is sufficient for an agent to understand 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% with adequate descriptions for each parameter. The description provides overall context but does not add significant per-parameter semantics 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 tool's function: generating a complete interior specification from hex values. It specifies input range (2-8 hex values) and output contents, distinguishing it from siblings like get_harmonies 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 implies use when a full palette specification is needed, but lacks explicit guidance on when to use versus alternatives or when not to use. No sibling differentiation is provided in the description.

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 explains the tool's behavior: it returns verdicts on what works, clashes, missing, and suggests a missing archive colour. Annotations declare readOnlyHint true, and the description adds rich 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?

The description is somewhat lengthy but front-loaded with the core question and includes concise examples. Every sentence adds value, though some trimming could improve conciseness without losing 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 and the presence of an output schema, the description is complete. It covers purpose, usage, examples, and expected output, ensuring the agent can effectively select and invoke the tool.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds meaning by explaining acceptable labels (dress, bag, shoes) and providing usage examples, enhancing parameter 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's purpose: answering style matching questions by submitting outfit items as hex values and labels. It provides specific examples and distinguishes itself by focusing on 'does this go with that?' with historical context, differentiating 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?

The description includes examples and implies when to use the tool (style questions about outfits). However, it does not explicitly state when not to use it or compare it to sibling tools like compare_colours or colour_story, leaving some room for ambiguity.

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