Colour Memory

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

The description adds value beyond the readOnlyHint annotation by specifying the exact output: contrast ratios and pass/fail grades. It does not disclose any potential side effects, which is appropriate for a read-only operation. However, it could mention any limitations (e.g., only supports hex colors).

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 front-loads the action and key outputs. No unnecessary words; every part earns its place.

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

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

For a tool with two well-documented parameters, an output schema, and a clear purpose, the description is complete enough. It could be improved by noting any constraints (e.g., hex format validation) or behavior when background is omitted, but it is sufficient 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 description coverage is 100%, so the schema already documents the parameters. The description adds context by connecting 'foreground hex' and 'background' to the parameters, but does not provide additional semantic meaning beyond what is in the schema.

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

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

The description clearly states the verb 'Return', the resource 'WCAG 2.1 contrast ratios and AA/AAA pass/fail grades', and the inputs 'foreground hex against a background'. It distinguishes itself from sibling tools like accessibility_font or accessibility_rules by focusing specifically on contrast calculation.

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

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

The description implies the tool is used for checking contrast ratios against WCAG standards, but does not explicitly state when to use it versus alternatives like accessibility_simulate or accessibility_matrix. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations declare readOnlyHint=true, so no contradiction. The description adds context about ranking and recommendations, but does not disclose additional behavioral traits such as error handling or performance characteristics. With annotations covering safety, the description is adequate but not rich.

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 front-loaded with core purpose and conveys all necessary information. No excess 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 simplicity of the tool (2 required params, output schema exists), the description provides sufficient context about input-output behavior. Could be improved by mentioning constraint like 'hex values must be valid' or 'contrast ratio calculated per WCAG 2.1', but currently adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the tool ranks the palette by contrast ratio and provides recommendations, which goes 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 uses specific verbs ('return') and resources ('candidate foreground colours ranked by contrast ratio with WCAG grades and recommendations'), clearly distinguishing the tool from siblings like accessibility_check or palette_compare.

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

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

The description only states what the tool does, without any guidance on when to use it versus alternatives, prerequisites, or when not to use it. 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 already set readOnlyHint=true, so no contradiction. The description adds that the tool returns a full matrix of combinations with grades and summary, which is 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?

Two concise sentences: first explains input and output, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

Given the presence of output schema (not shown but indicated), the description appropriately covers the input and output summary. It explains the tool's purpose and when to use it, making it complete for selection and invocation.

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

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

Schema coverage is 100% for the only parameter 'palette', with clear description (array of hex strings, min 2 max 20). The description reiterates 'palette array' but adds no new semantics, so baseline of 3 is appropriate.

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

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

The description clearly states it accepts a palette array and returns every foreground/background combination with contrast ratio and pass/fail grades for AA and AAA standards. It also distinguishes itself from sibling tool 'accessibility_check' by suggesting it as a bulk alternative.

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

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

The description explicitly says 'Use this instead of calling accessibility_check multiple times for a palette,' providing clear guidance on when to use this tool over the sibling. It does not mention when not to use it, but the context is sufficient.

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

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

Annotations already declare readOnlyHint=true, so the description builds on that by adding 'Deterministic, no LLM cost,' which is valuable behavioral context. It also enumerates the exact outputs, giving an agent a clear picture of what to expect. Slightly less than perfect because it doesn't mention any side effects or limits, but those are not needed given the annotations.

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

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

Two sentences that efficiently convey the purpose, outputs, and a behavioral trait. No redundant words, and every clause carries weight.

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

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

Given that the tool has an output schema (not shown but indicated as present), the description adequately lists the categories of returned rules without needing to detail structure. The description is complete enough for an agent to decide to invoke this tool.

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

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

The input schema has 100% coverage with 'Array of hex values' for the palette parameter. The description mentions 'palette WCAG matrix' but adds minimal extra semantic meaning beyond the schema. Baseline 3 is appropriate since the schema already documents the parameter well.

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

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

The description clearly states what the tool does: 'Convert a palette WCAG matrix into actionable design-system rules.' It lists specific outputs like safe pairs, AA-only pairs, etc., distinguishing it from siblings like accessibility_matrix or accessibility_check which compute the matrix or check individual pairs.

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 for when to use the tool (converting a WCAG matrix into rules) and highlights a key differentiator: 'Deterministic, no LLM cost.' This implies using it when deterministic, cost-effective results are needed. However, it does not explicitly state when not to use it or name 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 by specifying the algorithm used (Brettel-Vienot-Mollon). Annotations already indicate readOnlyHint=true, so there is no contradiction. No side effects or limitations are disclosed, but the tool is simple.

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 includes the key verb, output, and algorithm. 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 low complexity (1 required parameter, existing output schema), the description fully covers the tool's behavior. The output format is delegated to the output schema.

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

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

Schema coverage is 100% with a clear example for the single parameter. The description does not add additional parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: returning simulated hex values for three specific types of color blindness using a named model (Brettel-Vienot-Mollon). This distinguishes it from sibling tools like accessibility_check.

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

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

Usage context is implied by the name and description but no explicit when-to-use or when-not-to-use guidance is provided. 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?

The description explains the full process: fetching a historically grounded archive palette, producing an agent brief, colour tokens, model-specific prompts, negative prompt, and lighting notes. It also discloses the behavior of locked_palette (no archive query). No contradiction with readOnlyHint annotation—the tool does not modify any data.

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 (5 sentences) and well-structured: first sentence states purpose, then lists outputs, supported models, an example, and usage instruction. 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?

Given the tool has 8 parameters, 100% schema coverage, and an output schema, the description adequately covers the workflow, supported models, and special parameter behaviors. It provides sufficient context for an AI agent to invoke the tool correctly.

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

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

Schema descriptions cover all 8 parameters (100% coverage), so the baseline is 3. The description adds value by explaining how parameters like locked_palette and allowed_archives affect behavior, and mentions the output products, providing context beyond the schema alone.

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

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

The title and description clearly state the tool generates a complete colour direction package for another AI. It lists specific outputs (archive palette, agent brief, colour tokens, prompts, lighting notes) and supported models (midjourney, flux, etc.), distinguishing it from sibling tools like palette_generate or colour_strategy.

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 an example (task='luxury hotel bedroom', concept='Ottoman winter luxury') and states the tool is for making 'Colour Memory the colour layer for other AI systems'. However, it does not explicitly state when not to use it or contrast with sibling tools, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true, and the description adds detail on return values (fidelity score, distances, verdict). However, it does not elaborate on error handling or side effects beyond what annotations provide, which is adequate but not exceptional.

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

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

The description is four concise sentences with no redundancy. Each sentence serves a purpose: defining the tool, specifying inputs, summarizing outputs, and providing usage order. Perfectly 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?

Given the presence of an output schema (mentioned in context), the description adequately covers purpose, inputs, outputs, and workflow placement. It leaves no obvious gaps for an agent to misinterpret or misuse the tool.

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

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

Input schema has 100% description coverage, and the description adds context by linking target_palette to agent_brief colour_tokens and summarizing return values. This extra meaning helps the agent understand parameter relationships beyond raw 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 verifies colour fidelity in AI-generated images, specifying the action (verify), resources (image, palette), and purpose. It distinguishes itself from siblings like colour_compare or colour_metrics by focusing on verification against an agent_brief 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 explicitly states to use after agent_brief and image generation, providing clear when-to-use guidance. It does not explicitly state when not to use or list alternatives, but the workflow context is sufficient for an agent to apply correctly.

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 declare readOnlyHint=true, indicating no side effects. The description adds further transparency by stating 'No Claude call — pure archive data analysis,' confirming it is a safe, read-only operation. No contradictions or missing behavioral 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 comprehensive yet concise, using several sentences to convey purpose, outputs, and usage guidance. All information is front-loaded and each sentence adds value. Minor improvements could include slightly tighter wording, but overall it is well-structured.

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

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

Given the tool's complexity (multiple metrics and output types), the description fully details what is returned: health score, grade, issue counts, affected names, and a fix list. Combined with the presence of an output schema (as indicated by context signals), the description provides complete contextual information 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?

The schema covers 100% of parameters with a description for 'archive.' The tool description adds examples ('e.g. ''British'', ''Tingry'', ''Byzantine'') that help clarify the expected input values, going beyond the schema's basic description.

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

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

The description clearly specifies the tool's action ('Run a data quality audit'), the target resource (any named archive), and the outputs (entry count, health score, grades, issue counts, etc.). It distinguishes itself from sibling tools by focusing on data quality auditing rather than searching or status checks.

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

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

The description explicitly recommends usage contexts: 'Use before building new archive content to establish a baseline, or after a batch import to verify data quality.' It does not explicitly mention when not to use or alternatives, but the provided guidance is clear and sufficient for most decision-making.

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 finds an archive colour and uses Claude to generate creative text. This goes beyond the readOnlyHint annotation by detailing the generation process and output format. No contradictions with annotations.

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

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

The description is well-structured, starting with the core action, then explaining parameters, providing an example, and stating use cases. It is efficient but 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?

Given the tool has an output schema and the description explains return values (one-liner, short story, tweet), the description is complete. All necessary context for an agent to decide when and how to use the tool is present.

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?

Even though schema description coverage is 100%, the description adds significant value by providing concrete examples (e.g., 'love + red returns Shakespeare's dark green...') and explaining how each parameter is used in practice.

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: find the most surprising archive colour for a concept and generate a one-liner, short story, and tweet. It uses specific verbs and distinguishes from sibling tools by focusing on subversion of colour clichés.

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

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

The description provides clear context on when to use the tool ('for public-facing demos, content, and brand storytelling'). However, it does not explicitly mention when not to use it or compare it to alternatives among siblings.

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

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

Annotations declare readOnlyHint=true, which is consistent with the description stating it 'reports' and 'returns' a matrix (read-only). The description adds detail on the output structure (entries found, coverage grade, best match, needed source type), going beyond the annotation.

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

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

The description is concise: two sentences plus a usage instruction. It front-loads the core purpose and provides actionable guidance, though it could be slightly more compact.

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 only two parameters (one required) and an output schema implied, the description covers purpose, usage, output structure, and practical context. It is complete for an AI agent to understand when and how to use it.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description adds value by explaining how the 'themes' parameter is used (checked against archive) and what output fields are produced, despite not detailing 'archives' beyond the schema.

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

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

The description clearly states the tool's function: given a list of themes, report which are well-evidenced and which are missing/under-evidenced. It also describes the output (coverage matrix with grades) and distinguishes it from other tools by specifying when to use it (before building reports).

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

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

The description explicitly says to use this tool BEFORE building archive_report_brief or brief_forensic, and explains the benefit of preventing incomplete reports. It does not contrast with sibling tools like archive_evidence_gap, but the usage context is clear.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this by describing checks and scoring (no mutation). It adds behavioral details beyond annotations: detection of date range and specific archives, and the return fields. This provides useful transparency 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 two sentences, front-loaded with the core action, followed by rationale and return details. Every sentence adds value, no redundancy. Efficient and well-structured.

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

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

Given the tool has an output schema and 4 parameters, the description covers purpose, detection logic, importance, and return fields comprehensively. It provides enough context for an agent to understand when and how to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for the parameters (e.g., 'entries' are colour entries, period parameters define the historical period), but does not significantly enhance understanding beyond the schema's descriptions. The example illustrates usage effectively.

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 checks colour entries for anachronism risk, detecting date mismatches and known modern archives. It distinguishes itself with a concrete example (preventing 2011 racing silk registration from being presented as Georgian evidence), making the purpose specific and actionable.

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

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

The description explicitly says it's 'Essential for historical documents' and gives a scenario (Georgian evidence). It implies when to use but does not explicitly state when not to use or suggest alternatives. Still, the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by detailing the return structure (nearest archive support, support level, source type needed, safe wording). It does not contradict annotations and provides useful behavioral context beyond the schema.

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

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

The description is 4 sentences, front-loaded with the core operation, followed by an illustrative example and use-case list. 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 output schema exists, the description sufficiently covers return values (support level, source type, safe wording) and provides an example. All 4 parameters are covered in schema, and the purpose is fully explained for the target workflows.

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 an example (hex #4A535C + proposed claim 'cyanosis in a death chamber') that illustrates parameter usage, and reinforces the meaning of 'archive' and 'n_candidates' in context.

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

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

The description states the tool's action precisely: 'Given a hex value and a proposed claim about it, return whether the archive supports that claim, what is missing, what kind of source would be needed, and safe agent wording.' This specific verb+resource combination clearly distinguishes it from siblings like archive_search or archive_coverage_gap.

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

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

The description provides usage context ('anti-hallucination endpoint', 'essential for museum, documentary, editorial, legal, and forensic workflows') but does not explicitly state when not to use it or name alternative tools. The guidance is implied rather than explicit.

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

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

Annotations indicate readOnlyHint=true, which aligns with the read-only nature. The description adds behavioral details about the returned fields and the separation of fact, derivation, and interpretation. There is no contradiction with annotations.

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

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

The description is two sentences long with no wasted words. It efficiently conveys purpose, output, and importance, and is front-loaded with the key action and result.

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 context: what it does, what it returns (list of fields), and when to use it. It is complete for an informed 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% for the single parameter 'colour_name', which already has a description. The tool description adds examples of colour names and context ('archive colour'), marginally enhancing understanding beyond the schema.

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

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

The description clearly states the tool explains provenance of an archive colour with explicit separation of documented fact, hex derivation, and cultural interpretation. It uses specific verbs and resource, distinguishing it from sibling tools by focusing on provenance and trust.

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 identifies this as the trust endpoint for answering 'how do you know this?' and states it is essential for intellectual honesty. This provides clear context for when to use, though it doesn't explicitly mention when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint=true. The description adds valuable context: it reveals it makes 'Two Claude calls total' and details the rich output structure, enhancing understanding of behavior beyond the safe read nature.

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

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

The description is information-dense and well-structured, front-loading the purpose, listing inputs and outputs, and concluding with usage guidance. Every sentence adds value for a composite 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?

With 7 parameters, an output schema, and no complex nesting, the description covers purpose, inputs, outputs, and usage thoroughly. It provides enough context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description lists the parameters again but does not add new semantic details beyond what the schema provides. No format constraints or examples are given.

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

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

The description clearly states it is a 'One-call complete archive research package' for documents, PDFs, or editorial briefs. It explicitly distinguishes itself from sibling tools by noting it replaces chaining multiple separate tools, making the purpose unambiguous.

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

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

The description explicitly says 'Use this first for any document workflow', providing clear when-to-use guidance. It also explains what it replaces, implying when not to use individual tools.

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

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

Annotations already declare readOnlyHint=true, so the description's statement that it performs search is consistent. The description adds context about the scope (archive colour names and notes) and types of queries, but does not disclose additional behavioral traits like limits, edge cases, or performance characteristics.

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

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

The description is two sentences, front-loads the core function, and every sentence adds value. No wasted words; it efficiently communicates purpose and differentiation.

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 (which handles return value documentation), the description covers all key aspects: purpose, usage guidelines, and behavioral context. With 5 parameters and 100% schema coverage, no gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds some minor value by expanding query examples and explaining the include_full parameter's workflow context, but does not deeply 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 explicitly states it performs full-text keyword search across archive colour names and notes, and lists diverse searchable aspects (name fragment, material, etc.). It also distinguishes itself from the sibling tool 'query_conceptual' by stating it complements conceptual embedding search with exact keyword matching.

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

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

The description clearly indicates when to use this tool (exact keyword matching) and contrasts it with conceptual embedding search. It does not explicitly list when not to use, but the sibling differentiation provides strong 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 already declare readOnlyHint=true, and the description adds behavioral context by listing the exact data returned, enhancing understanding beyond the annotation. 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?

Single sentence, front-loaded with the action and outcome, then lists specifics. No superfluous words.

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

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

Given zero parameters and presence of output schema, the description fully covers the tool's purpose and return values. No gaps.

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

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

There are zero parameters, so schema coverage is 100%. The description adds meaning by detailing what the tool returns, which is valuable since there is no input schema to explain.

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 live archive status and lists specific fields (total colour count, per-archive breakdown, embedding model, search engine state, API version). It distinguishes itself from siblings which perform actions like audit, search, or generation.

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

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

The description implies use for querying status, but does not provide explicit when-to-use or when-not-to-use guidance relative to siblings like archive_audit or archive_search. No alternatives 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?

The annotation declares readOnlyHint=true, so the tool is known to be read-only. The description adds behavioral context beyond the annotation: 'Deterministic. No LLM cost.' This informs the agent about reproducibility and resource consumption, which is valuable.

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

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

The description is three sentences long, front-loading the key outputs in the first sentence and adding deterministic/ cost traits in the third. No redundant or unnecessary words; every sentence adds value.

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

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

Given that an output schema exists, the description does not need to detail return values. It covers the types of outputs, behavioral traits, and scope. However, it does not mention any prerequisites (e.g., palette must contain at least one valid hex) or the structure of the returned JSON, which are partially covered by the schema.

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

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

Schema description coverage is 100%, meaning all 5 parameters (market, medium, palette, use_case, brand_category) are already documented with descriptions in the schema. The tool description adds no additional parameter-level information, so 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 what the tool does: 'Returns CSS variables, Tailwind config, Figma tokens JSON, citation cards, and a Markdown brand guide.' It uses a specific verb ('Returns') and lists the resources, distinguishing it from siblings like brand_audit or brand_system by emphasizing it is a complete export pack.

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

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

The description implies usage for generating a complete brand asset pack with 'Everything a brand team needs to ship,' but does not explicitly state when to use this tool versus alternatives (e.g., brand_system for system design, brand_report for reports). No exclusions or when-not guidance is provided.

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

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

Annotations declare readOnlyHint: true, meaning it is a read-only operation. The description adds valuable behavioral context: 'All computed data -- no LLM cost', revealing that no generative AI consumption occurs. This goes beyond annotations to inform about cost implications and computational nature.

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

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

The description is two sentences: the first front-loads the core purpose and lists inputs/outputs, the second adds value propositions and replacement guidance. Every word earns its place; no extraneous content.

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

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

Given the tool's moderate complexity (5 parameters, output schema present), the description fully covers inputs, outputs, behavior, and alternative usage. The existence of an output schema relieves the description from explaining return values, and it still provides ample context for correct invocation.

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

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

All 5 parameters are fully described in the input schema (100% coverage). The description merely lists the parameters again without adding new semantic meaning or usage details beyond what the schema provides. Baseline score of 3 is appropriate as the description does not hinder understanding but also does not enhance it.

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

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

The description clearly states it performs a 'Complete brand colour intelligence audit in one call', listing specific inputs and outputs. It distinguishes from sibling tools by explicitly saying it 'Replaces chaining accessibility_matrix + cultural_risk_assessment + palette_verdict separately', making the unique purpose unambiguous.

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

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

The description provides explicit guidance: use this tool for a single comprehensive audit instead of chaining multiple separate tools. It also advises passing results to an LLM for narrative generation, indicating a clear after-use step. This makes when and when-not to use the tool very clear.

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

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

Annotations declare readOnlyHint=true, and the description adds context about outputs (CIEDE2000 distances, distinctiveness score, verdict, recommendation) and use of archive context, increasing transparency beyond annotations.

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

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

Two concise sentences that front-load the purpose and efficiently cover inputs and outputs without waste.

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

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

Given the tool's complexity and presence of an output schema, the description covers the main use case and return values adequately, though could mention constraints like competitor count.

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

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

Schema coverage is 100% with good descriptions; the description lists parameters but does not add significant semantic depth 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's purpose: checking if a brand can own a color against competitors in a market, using specific verbs and distinguishing it from siblings like colour_compare.

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

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

Explicitly states when to use it ('before committing to a brand colour in a competitive market') and what it replaces, but does not explicitly mention when not to use it or alternatives.

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

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

Annotations already provide readOnlyHint=true, indicating a safe read operation. The description adds valuable behavioral context: it runs internally, requires no chained calls, cannot be blocked by safety filters, and completes in two Claude calls. This goes beyond the annotations to inform the agent about execution characteristics.

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

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

The description is informative and well-structured: a clear opening sentence, a comprehensive list of outputs, and explicit usage guidance. While it is somewhat lengthy for a tool description, every sentence adds value and the structure is logical. Slight trimming of the output list could improve conciseness, but it remains effective.

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

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

Given the tool's complexity (7 parameters, nested objects, and an output schema), the description covers all necessary aspects: purpose, inputs, outputs, usage conditions, and differentiation from alternatives. The existence of an output schema means return values need not be explained, so the description is complete and self-sufficient.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's meaning. The description merely lists the input parameters (hex, brand context, markets, etc.) without adding new details or constraints. Thus, it meets the baseline but does not 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 explicitly states it is a 'one-call complete brand colour intelligence report' and lists the specific outputs (e.g., archive anchor, cliche contradiction, colour DNA). It clearly distinguishes itself from chaining multiple sibling tools like colour_strategy and cliche_breaker, making the purpose precise and unique.

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

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

The description provides explicit usage guidance: 'Use this instead of chaining colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief separately.' It also notes that it 'runs entirely internally' and 'cannot be blocked by agent safety filters,' giving clear context on when and why to use this tool over 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 'Deterministic. No LLM cost.' beyond the readOnlyHint annotation, providing valuable behavioral insight. It also details the extensive output, which helps the agent understand the tool's deterministic and cost-free nature.

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

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

The description is extremely concise: two sentences that front-load the core function, followed by a list of outputs and two key properties. Every sentence adds 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 tool's complexity (returning many items), the description covers the main outputs. It is complete enough for an agent to understand what it does, though it could mention prerequisites or usage context for very complex scenarios.

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 5 parameters. The description does not add new meaning beyond what the schema provides, so a baseline of 3 is appropriate. The listing of output items indirectly relates but does not enhance 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 clearly states 'Complete brand colour system in one call', specifying the verb (returns) and the comprehensive resource (colour roles, maps, guidance, rules, tokens, cards). It distinguishes from sibling tools that focus on individual aspects like accessibility or audit.

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

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

The description implies use when a full brand color system is needed, contrasting with the specialized sibling tools. However, it does not explicitly state when not to use it or mention alternative tools, though the context of siblings 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?

The description adds value beyond the readOnlyHint annotation by specifying the exact data returned (hex, archive, provenance, cultural notes). No contradictions observed.

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, compact sentence with no unnecessary words. All key information is conveyed efficiently.

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

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

Given the existence of an output schema, the description appropriately omits return value details. However, it could briefly mention the recommendation to use slug for reliability, enhancing completeness.

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

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

Schema coverage is 100% with descriptions for both name and slug. The description does not add additional semantic meaning or clarify the preference for slug over name, so it does not exceed the baseline.

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

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

The description clearly states the verb 'look up', the resource 'named colour', and the return values ('hex, archive, provenance, and cultural notes'). This strongly distinguishes from sibling tools like colour_compare or colour_forensics.

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

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

The description implies usage for retrieving details of a named colour but provides no explicit guidance on when to use this tool over alternatives, nor does it mention the preferred parameter (slug vs name) for reliable retrieval.

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; description confirms no mutation and adds detail on return types (harmony, clash, contrast, rules). 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?

Single, front-loaded sentence with no wasted words; every detail serves a purpose.

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

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

Given low parameter count, rich schema, and output schema, the description fully covers purpose, inputs, and outputs.

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; description rephrases 'context' enum and adds meaning by stating the tool returns specific outputs, exceeding baseline.

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

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

The description uses a specific verb ('assess') and resource ('colours as a combination') with context variety, clearly distinguishing from siblings like 'colour_compare' or 'colour_harmonies'.

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

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

Describes the tool's function and outputs clearly, implying use for combination evaluation, but lacks explicit when-to-use or alternatives.

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

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

The annotations already declare readOnlyHint=true, and the description confirms a non-destructive comparison. It adds value over annotations by detailing the types of analysis performed (perceptual, semantic, cultural) and the specific metrics returned (CIEDE2000, LRV, chroma, etc.), which helps the agent understand what to expect.

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

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

The description is concise at two sentences, with front-loaded purpose and clear distinction from siblings. Minor redundancy (e.g., 'deep perceptual and semantic comparison' and then listing metrics) but 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 (not shown but noted), the description does not need to explain return values. It covers inputs, use cases, and the nature of the comparison comprehensively. The tool is a focused comparison with clear scope.

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

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

Schema coverage is 100% for the two parameters (hex_a, hex_b). The description does not add new information beyond the schema; it implicitly confirms hex values. Baseline of 3 is appropriate as the schema already does the heavy lifting.

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

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

The description uses a specific verb ('compare') and resource ('two colours'), clearly distinguishing from siblings by explicitly stating 'Not a harmony tool — this is a decision and reasoning tool.' It enumerates the precise outputs (LRV, chroma, hue angle, etc.) and contrasts with harmony tools in the sibling list.

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

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

The description states when to use the tool: 'Use when choosing between two colours or explaining why one works better than another.' It also contrasts with a harmony tool, providing context. However, it does not specify when not to use it or mention alternatives explicitly, though the sibling list implies alternatives.

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

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

Annotations indicate readOnlyHint=true, and the description confirms a read-only analysis by stating it 'returns warnings, positive associations, and context-dependent readings.' It adds value beyond annotations by specifying the basis ('documented cultural colour associations') and the outputs (warnings, market flags).

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

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

Two sentences, front-loaded with the core purpose. Every word serves a purpose without redundancy. Clear 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?

Given the presence of an output schema (not shown but indicated), the description sufficiently covers the tool's purpose, parameters, and behavioral context. It addresses the complexity of cultural risk assessment without missing critical elements.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining what the assessment covers (symbolic weight, regional taboos, religious associations) and the context of use, which goes beyond the schema's technical 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 uses a specific verb 'assess' and clearly identifies the resource ('cultural risk of a colour or palette'). It distinguishes from sibling tools like 'accessibility_check' and 'brand_audit' by focusing on cultural sensitivity, symbolic weight, and regional taboos.

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

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

Explicitly states 'Use before deploying a colour in a global brand, product, or campaign context,' providing clear when-to-use guidance. It does not explicitly define when not to use, but the context implies it is for cultural assessment, not general color theory.

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

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

Annotations already declare readOnlyHint: true, and the description adds context: 'No Claude call -- pure archive and physics data. Fast and cacheable.' This discloses performance characteristics and data source, which goes beyond the annotation. 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 concise (6 sentences), with the first sentence immediately stating purpose. Every sentence adds value: output fields, data source, performance, and usage guidance. 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 simple one-parameter tool with an output schema, the description covers purpose, outputs, performance, and use cases comprehensively. It could mention error handling or edge cases (e.g., invalid hex), but overall it is complete enough for an agent to decide and use the tool.

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

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

Schema coverage is 100% with one well-described parameter (hex). The description does not add new parameter details but explains how the tool uses the hex to produce outputs, which is sufficient given high schema coverage.

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

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

The description clearly states the tool produces a 'Compact semantic fingerprint' for any hex colour, listing specific output fields. It distinguishes itself from siblings like 'colour_story' by positioning this as a quick, cacheable semantic fingerprint for filtering and comparison, avoiding long prose.

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

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

The description explicitly says to use it 'when an agent needs to reason about a colour semantically without reading long prose' and for 'filtering, ranking, or comparing colours.' While it doesn't explicitly name alternative tools or when not to use it, the context and sibling list imply other tools for deeper analysis.

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?

Disclosed as read-only via annotation; description adds value by explaining return structure (verdict, risks, light behaviour) and backing methods (CIEDE2000, Claude material knowledge). 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?

Single paragraph is well-structured: purpose, output, backing, examples. No fluff, but could be slightly more concise. Earns its length.

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

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

Moderate complexity with output schema present; description lists key outputs and parameter contexts. Examples ground usage adequately. No major gaps.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. Description does not add significant semantic beyond schema, but lists examples that contextualize usage. 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 the tool assesses safety for physical application, with specific verb and resource. Distinguishes from siblings like colour_cultural_risk or colour_verdict by focusing on physical application safety.

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?

Clear use case for assessing colour safety in physical contexts. Lacks explicit exclusions or alternatives, but the description implies scope effectively.

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 is consistent with the readOnlyHint annotation, confirming it is a read operation. However, it does not elaborate on any other behaviors (e.g., data source, authentication). The annotation already handles the safety profile, so the description does not need to repeat it, but it could add context about the 'archive colours' mapping.

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, front-loaded sentence that efficiently conveys the tool's purpose and output. 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?

The description is concise but has a slight inconsistency: it implies all harmony types are always returned, yet the 'harmony_types' parameter allows filtering. Additionally, 'named archive colours' is not explained. With an output schema present, return values are covered, but this issue reduces completeness.

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

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

Schema description coverage is 100%, providing baseline of 3. The description adds value by listing the specific harmony types (complementary, triadic, analogous, split-complementary), which enhances understanding of the 'harmony_types' parameter beyond the schema's generic 'Harmony types to include'.

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 complementary, triadic, analogous, and split-complementary harmonies matched to named archive colours. The verb 'Return' with specific resource types distinguishes it from sibling tools like colour_combination or palette_generate.

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

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

No guidance on when to use this tool versus alternatives. With many sibling tools (e.g., colour_combination, colour_compare), the description fails to provide context or exclusions, leaving the agent to guess.

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 behavioral context by stating the tool is 'backed by the nearest archive colour's cultural provenance' and lists the outputs. No contradiction; it provides useful insight 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 three sentences, front-loaded with the main action, and every sentence adds value. No redundant or missing information.

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

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

Given the presence of an output schema and the description listing the outputs explicitly, the tool is fully described. No gaps remain for an AI agent to understand what to expect.

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

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

Schema coverage is 100% with each parameter having a description. The description summarizes the tunability by audience and tone but does not add new semantic details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a hook sentence, three-sentence story, tweet, image prompt, and follow-up questions for any hex colour. It distinguishes from siblings by specifying the range of outputs and the backing by archive colour provenance, which is unique among sibling tools like colour_story.

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

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

The description provides explicit use cases: 'make archive colours shareable, to generate content, or to power a public-facing colour chat experience.' It does not explicitly mention when not to use or alternatives, but the context signals and sibling list imply many tools exist for different purposes.

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

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

The readOnlyHint annotation is present and consistent with the described search action. The description adds that it covers specific brands ('Farrow and Ball and Little Greene') but does not detail matching behavior (e.g., distance metric, handling of multiple results) or any limitations. It provides adequate but not exceptional context beyond the annotations.

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

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

The description is a single sentence of 14 words, front-loading the core purpose. Every word contributes meaning; there is no redundancy or fluff. It is optimally concise for its content.

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

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

Given the complexity (3 parameters, output schema present), the description is brief but covers the essential purpose. However, it omits usage context to differentiate from numerous color-related sibling tools (e.g., colour_compare, palette_compare). The output schema likely handles return value documentation, so the description is complete for simple tasks but lacks strategic guidance.

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 are described in the input schema (100% coverage). The description mentions the brands in the main text but does not elaborate on parameter semantics beyond what the schema provides. Baseline score of 3 is appropriate as the description adds minimal extra meaning.

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: 'Find the nearest named colour in commercial paint systems including Farrow and Ball and Little Greene.' It uses a specific verb ('find') and identifies the resource ('nearest named colour in commercial paint systems'), effectively distinguishing it from sibling tools like 'colour_namer' or 'colour_compare'.

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

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

The description implies use for matching a hex to commercial paint brands. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., when to use colour_compare or colour_namer). No exclusions or context about prerequisites are provided, leaving the agent to infer 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, indicating a safe read operation. The description adds valuable context about the specific metrics returned and illuminants considered, which goes beyond the annotation.

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

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

The description is a single, focused sentence that lists all key outputs efficiently, with no redundant or extraneous information.

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

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

Given the presence of an output schema and the straightforward functionality, the description covers all relevant aspects: the type of metrics, specific values, and illuminant conditions, making it complete for agent 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% and the parameter hex_val is well-described. The description adds no additional semantics beyond what the schema provides, maintaining the baseline score.

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

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

The description explicitly states the tool returns perceptual colour metrics and lists specific outputs (LRV, chroma, hue angle, warmth classification, illuminant shifts), clearly distinguishing it from sibling tools like colour_compare or colour_harmonies.

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

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

The description implies use for obtaining numeric colour properties but offers no explicit guidance on when to use versus alternatives, nor any exclusions or prerequisites.

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 a simulation. The description adds value by explaining the use of CIE Lab subtractive model, perceptual accuracy, and the output components (mixed hex, archive match with cultural context). The example further illustrates behavior. No contradictions.

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

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

The description is three sentences followed by an example, all front-loaded: purpose first, then behavior, then example. No extraneous information. Every sentence earns its place.

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

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

Given the tool's complexity (3 parameters, output schema exists), the description covers purpose, model, output, and an example. It is complete for an agent to understand what the tool does and what it returns. Minor omission: the specific archive used for matching is not named, but this is not critical 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?

Schema coverage is 100% with all three parameters described. The description does not add new parameter details beyond the schema, but it reinforces usage through the example (Prussian Blue #003366 and Yellow Ochre #C8A600) and mentions the ratio default of 0.5. This is adequate but 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?

The description clearly states the tool simulates subtractive mixing of two colours in CIE Lab space, distinguishing it from RGB screen blending. It specifies returning a mixed hex value and nearest archive match with cultural context, and provides an example (Prussian Blue and Yellow Ochre). This separates it from sibling tools like colour_combination or colour_compare.

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

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

The description implies use for perceptually accurate paint/ink mixing by contrasting with RGB blending. However, it does not explicitly mention when not to use it or name alternatives among siblings. The context is clear enough for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds context about archive grounding, but does not disclose potential limitations or error handling. It adds some value beyond annotations.

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

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

The description is compact (4 sentences) and front-loaded with purpose. The last sentence ('The core of...') is slightly vague but not wasteful. Overall 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 tool's complexity (5 params, output schema), the description covers key aspects: input, styles, archive grounding, and use case. It does not detail output structure, but the output schema handles that. Missing some guidance on parameter interactions, but sufficient.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The description lists style options which are already in the schema. It does not add new semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('archive-verified colour names'), and clearly indicates the input (hex value) and style options. It distinguishes from sibling colour tools by emphasizing archive grounding and naming styles.

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

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

The description states it is for generating colour names with various styles, and positions it as central to the Shopify product naming use case. However, it does not explicitly tell when not to use it or name 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, and the description adds context about the output (multiple token formats) and the algorithm ('Archive-grounded name source with dE2000 distance'), enhancing transparency 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?

Two sentences, no wasted words. The first sentence lists all output formats clearly, and the second adds contextual detail about the naming source.

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 (not shown), the description need not detail return values. It covers the tool's purpose, inputs, and key behavior (token formats, algorithm). Some minor details like pagination or error handling could be added but are not essential.

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

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

Schema coverage is 100%, so the description adds no additional meaning to the parameters beyond what the schema provides. The description mentions a hex example and optional archive filter, matching schema.

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

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

The description explicitly states 'Return every developer token format for a hex value' and enumerates specific formats (CSS variable, kebab-case, etc.), making the tool's function clear and distinct from siblings like colour_namer or colour_hooks.

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

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

The description implies usage for converting hex values to developer tokens but does not explicitly state when not to use or provide alternatives. It is clear enough for the main use case.

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

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

Annotations declare readOnlyHint=true, which the description aligns with. The description adds that the output is a narrative, but doesn't disclose additional behavioral traits like rate limits or authentication needs. It neither contradicts nor significantly extends 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 concise: two sentences and an example. Information is front-loaded and every sentence contributes value without redundancy.

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

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

Given the tool's simplicity (2 params, output schema exists), the description fully covers what the tool does, what it returns, and when to use it. No gaps identified.

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

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

Schema description coverage is 100%, so the description adds minimal value beyond the existing parameter descriptions. The example '#DC143C' is helpful but also present in the schema. No new semantic depth added.

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 about a colour given a hex value. It distinguishes from sibling tools like colour_cultural_risk or colour_forensics by focusing on cultural journey, history, and archive names.

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 provides clear use cases: image generation prompts, brand storytelling, creative briefs. Though it doesn't explicitly exclude other scenarios or name alternatives, the context is sufficient for selecting this tool.

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

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

Annotations already declare readOnlyHint=true, so description adds context on the analyses performed but does not introduce new behavioral traits. It appropriately matches the read-only nature.

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

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

Description is concise yet comprehensive, front-loading purpose and listing inputs and outputs efficiently. Every sentence adds value, and examples enhance understanding 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 complexity (5 params, nested objects, output schema exists), the description covers all key aspects: inputs, outputs, and use cases. It is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description groups inputs and lists outputs, adding meaning beyond parameter descriptions. It provides a high-level overview of how parameters relate to 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 explicitly states it's a 'flagship commercial endpoint' that combines multiple analyses (archive grounding, verdict, brand fit, etc.), clearly distinguishing it from sibling tools that likely perform individual analyses. Verb 'combines' and resource 'colour strategy' are specific.

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 comprehensive colour strategy via 'flagship commercial endpoint' and provides examples of use cases. However, it does not explicitly state when not to use it or list alternatives, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds value by specifying the tool produces a chronological order and gives an illustrative example (e.g., deep blue through history), beyond what annotations provide.

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

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

The description is three concise sentences plus an example, with no fluff. It is front-loaded with the core action and efficiently conveys the tool's 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?

With only 2 parameters and an output schema present, the description adequately covers the tool's behavior. It explains the chronological ordering and provides a concrete example, leaving no major gaps for an AI agent to misunderstand.

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

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

Schema description coverage is 100%, so the schema already explains both parameters. The description adds context with an example for hex but does not elaborate on 'tolerance' beyond the schema. Baseline 3 is appropriate since the description does not significantly extend meaning.

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

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

The description clearly states the tool's purpose: given a hex value, it traces the colour's appearances across cultures and centuries in chronological order. It uses a specific verb ('traces') and resource ('colour appearances'), and the example distinguishes it from sibling tools like colour_story or colour_forensics by emphasizing chronological history.

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 indicates it is 'essential for understanding why a colour carries the weight it does,' implying use when historical context is needed. While it lacks explicit when-not-to-use or alternative suggestions, the sibling context and example provide clear guidance.

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

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

Annotations indicate readOnlyHint=true, and the description reinforces a read-only operation by stating it returns data. However, it does not disclose specific behavioral traits like whether the data is fetched from a database or any authorization needs, but the annotation already covers the safety profile.

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

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

Two sentences, front-loaded with the main action, no wasted words. Very concise and to the point.

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

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

Given one parameter and the presence of an output schema, the description adequately explains the return types (variants, lighter/darker, cultural siblings). However, it does not clarify what 'archival matches' or 'cultural siblings' mean, but overall complete for the tool's complexity.

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

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

Schema coverage is 100% with a clear description for the 'name' parameter. The description adds 'For any named archive colour,' which slightly reinforces the parameter meaning but does not add significant new semantics beyond the schema.

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

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

Clearly states the tool returns historical variants, lighter/darker versions, and cultural siblings for a named archive colour. It identifies the resource and action, and while it subtly distinguishes from siblings like colour_harmonies by mentioning cultural siblings, it does not explicitly differentiate from all colour-related tools.

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

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

Description says 'Essential for designers exploring around a colour,' implying use case for exploration. However, it lacks explicit guidance on when not to use this tool or mention of alternatives among the many sibling tools, such as colour_harmonies or colour_compare.

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. Description adds context about CIEDE2000 and Claude cultural intelligence, but does not explain limitations or edge cases. Behavior is partially transparent.

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

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

Description is concise with two sentences and a list of examples. Front-loaded with purpose, no wasted words. Slightly longer due to examples, but still 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 tool has 5 parameters (2 required) and an output schema, the description sufficiently explains the function and return values (verdict, strengths, risks). Could mention the structured output, but output schema covers that.

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

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

All parameters have schema descriptions, so baseline is 3. The tool description adds examples but does not significantly enhance meaning beyond schema.

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

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

Description clearly states the tool's purpose: evaluate a hex colour for a specific use case, market, and medium. It uses a specific verb 'evaluate' and resource 'hex colour', and distinguishes from sibling colour tools by focusing on a verdict outcome.

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 gives examples of when to use, but does not explicitly state when not to use or mention alternatives. The sibling list includes many colour tools, but the description lacks guidance on choosing this tool over others.

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

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

The description explains that the copy is grounded in archive provenance, not invented, which adds behavioral context beyond the readOnlyHint annotation. The generation action is consistent with a read-only operation on a database.

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 at around five sentences, with the main purpose clearly stated at the beginning. Each sentence adds meaningful information, though some minor redundancy could be removed.

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 lists all expected outputs and mentions the archive provenance, providing sufficient context for an agent to understand what the tool does and what to expect. Given the presence of an output schema, the description is adequately complete.

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

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

The schema covers all parameters with descriptions, and the description adds value by providing concrete examples of inputs and their combinations, helping an agent understand how to use the parameters effectively.

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

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

The description clearly states the tool generates complete ecommerce product copy for a given colour, listing specific inputs and outputs. It distinguishes itself from sibling tools like ecommerce_namer by focusing on full copy generation rather than just naming.

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

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

The description indicates the tool is directly useful for Shopify, WooCommerce, and editorial product pages, providing clear applicability. However, it does not explicitly mention when not to use it 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?

The description adds rich behavioral context beyond the `readOnlyHint=true` annotation, explaining the output structure (archive name, source citation, dE2000 distance) and asserting that names are 'archive-sourced, not invented' and defensible.

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, front-loading the action and listing inputs/outputs in compact, scannable sentences 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, the description fully explains the output fields and use cases, providing all necessary context for an AI agent to understand the tool's behavior and limitations.

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 by listing the style options ('geographical, poetic, material, literary, mixed'), which are not enumerated in the schema, and clarifies the role of each parameter, exceeding 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 uses a specific verb 'Generate' and resource 'archive-grounded colour names for up to 40 product SKUs', clearly distinguishing it from siblings like `colour_namer` by emphasizing ecommerce and archival sourcing.

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

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

The description states concrete use cases ('paint ranges, candle collections, fashion lines, homeware, cosmetics') but does not explicitly mention when not to use or compare to alternatives among siblings.

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

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

The description adds significant value beyond the readOnlyHint annotation by explicitly stating the image is never stored and processed only in memory. It also details the algorithms used (K-means++, Bradford adaptation) and the output data (archive name, cultural story, RAL, WCAG), fully disclosing behavior.

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

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

The description is a single coherent paragraph that front-loads the primary function followed by methods, use cases, and a privacy note. It is relatively concise, though could be slightly more structured (e.g., bullet points) for easier scanning.

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, full schema coverage, presence of output schema, and annotations, the description is complete. It covers input constraints, output details, privacy, and appropriate contexts, leaving no major 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. The description restates that the image is base64 encoded and mentions the default number of colours (5), but does not add new meaning beyond the schema. No contradictions or omissions.

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

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

The description clearly states the tool extracts dominant colours and matches to named archive entries. It specifies technical methods and use cases, but does not explicitly distinguish from sibling colour tools, though its unique combination of extraction and cultural provenance implies differentiation.

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

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

The description lists applicable domains (product photography, interiors, artwork, brand assets, mood boards), providing clear context for when to use. However, it does not mention when not to use or suggest alternative tools, missing explicit guidance.

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

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

Annotations indicate readOnlyHint=true (safe, read-only), and the description adds that photos are never stored. It also discloses the analysis process using Claude Vision and CIEDE2000 matching. Adds value beyond annotations.

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

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

The description is concise at four sentences, front-loaded with the main purpose, and each sentence adds essential information. No redundant content.

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

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

The description fully explains what the tool returns: seasonal type, depth, undertone, palette with provenance, and colours to avoid. Given the tool's complexity, this is complete and well-structured.

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%, but the description adds useful context: image_url is 'easier than base64 for MCP use' and image_base64 requires 'face clearly visible in natural light'. These details 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's purpose: upload a portrait photo and receive a personal colour analysis, including seasonal type, depth, undertone, and a curated palette. It distinguishes from sibling tools like palette_generate or image_palette by focusing on personal analysis using Claude Vision.

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?

While the description implies use for personal colour analysis with an example, it does not explicitly state when to use this tool versus alternatives (e.g., image_palette for generic palette extraction). No when-not guidance is provided.

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

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

Annotations already declare readOnlyHint=true. The description adds behavioral context by detailing the output fields (resonance score, material origin, social function, alignment reason, confidence) and score interpretation, which informs the agent about what to expect without contradicting annotations.

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

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

The description is efficiently structured: definition, scoring examples, input/output format, use cases, and a closing distinction. Every sentence adds value, and key information is front-loaded. No redundant or vague statements.

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

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

Given the presence of an output schema and the complexity of the tool, the description covers the main purpose, inputs, outputs, and use cases. It explains the scoring scale and output fields sufficiently. Minor omissions like error handling or edge cases could improve completeness, but overall it is well-rounded.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds input format details (name, hex, archive, source, notes) that align with the 'entries' parameter, but does not elaborate on the 'score_basis' parameter beyond the schema default. Overall, minimal additional value 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 is a proprietary semantic metric that scores alignment between material origin and social consequence of a colour. It provides specific score examples (1.00, 0.80, 0.50) and distinguishes itself from palette generators, making the purpose highly specific and unique among siblings.

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

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

The description explicitly lists use cases: investigative reports, forensic briefs, museum content, editorial PDFs. It also implies when not to use by contrasting with palette generators. However, it does not explicitly exclude other contexts or name alternative tools among siblings.

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

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

Annotations already mark this as read-only, so the description aligns by describing generation of outputs. It adds behavioral context by detailing what the output includes (rationale, light behaviour, etc.), which goes beyond the annotation. 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 paragraph that starts with the core purpose, then lists outputs and examples. It is efficient but could be slightly more structured (e.g., bullets). No wasted sentences.

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

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

Given the presence of an output schema and 100% parameter description coverage, the description provides a thorough overview of what the tool produces and its inputs. It covers the room brief use case comprehensively, leaving no critical gaps.

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

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

All 5 parameters are described in the schema (100% coverage). The description adds example values and context but does not significantly enhance understanding beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a complete interior colour specification from a concept. It lists specific outputs (60/30/10 assignments, paint matches, light behaviour, etc.) and provides example concepts, distinguishing it from siblings by mentioning a PDF version and stating it replaces a colour consultation.

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

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

The description gives examples of when to use the tool (e.g., 'bold maximalist living room') and points to the PDF variant for downloadable output. However, it does not explicitly state when not to use this tool versus sibling tools like palette_specify or palette_generate, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true; description adds that it's deterministic with no LLM cost and returns a live inventory, extending beyond annotations.

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

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

Three sentences, each purposeful: returns inventory, usage instruction, behavioral note. 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 no parameters and an output schema, description covers key aspects; could elaborate on 'usage notes' but overall adequate for a discovery 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?

No parameters exist (0 params, 100% schema coverage); description adds value by detailing return items (tool count, endpoint list, usage notes) beyond schema.

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

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

Clearly states it returns a live inventory of endpoints and MCP tools, distinguishing itself as the discovery tool among many siblings.

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

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

Explicitly says 'Use this first to discover what the API can do before making calls,' providing clear when-to-use guidance; lacks explicit when-not, but strong directional advice.

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

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

The description adds behavioral details beyond the `readOnlyHint` annotation, such as being deterministic and having no LLM cost. It also specifies return format (score, grade, fix list), which is helpful for the agent.

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

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

The description is concise with four sentences: what it does, what it scores, what it returns, and when to use it. No redundant information, perfectly 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 that an output schema exists, the description adequately covers the tool's purpose, inputs, and outputs. However, it could mention the output schema structure briefly for completeness.

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

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

The input schema has 100% description coverage, so the description does not need to add parameter details. The description provides context about scoring categories, but no additional parameter-level semantics beyond the schema.

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

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

The description clearly states that the tool performs a 'Full palette quality audit', listing specific dimensions (accessibility, cultural risk, etc.). It distinguishes itself from siblings like 'palette_verdict' by emphasizing 'Enterprise quality gate' and comprehensive scoring, but does not explicitly name alternatives.

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

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

The description provides a clear use case: 'use before shipping any palette'. However, it lacks guidance on when not to use this tool or how it compares to similar tools like 'palette_compare' or 'palette_verdict'.

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

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

The description discloses the tool's read-only nature (consistent with annotations) and specifies the return fields (timelessness scores, commercial strength, etc.), providing transparency beyond the annotations. However, it does not mention any limitations or side effects, which is acceptable for a read-only tool.

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

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

The description is concise, consisting of a single sentence that covers purpose and outputs. It is well-structured with front-loaded information, but could be slightly more readable by separating the output items.

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 does not need to detail return values, but it does list them, which adds helpful context. The 4 parameters are implied through the description's focus on comparison and use case. It is sufficiently complete for the tool's complexity.

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

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

With 100% schema coverage, the baseline is 3. The description adds minimal meaning beyond the schema, only referencing 'stated use case' which corresponds to the use_case parameter already described in the schema. No new semantics are provided.

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

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

The description clearly states it compares two palettes with a deep perceptual, cultural, and commercial focus, listing specific output metrics. However, among sibling tools like 'colour_compare' and 'palette_audit', the distinction is implied but not explicitly stated, slightly reducing clarity.

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

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

The description mentions a 'stated use case', implying the tool is context-dependent, but it does not provide explicit guidance on when to use this tool versus alternatives or when not to use it. The usage context is 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?

Annotations provide readOnlyHint=true, and the description adds context about the tool being 'historically grounded', 'sourced from the archive with documented history', and returning 'coordinated archive colours'. This provides useful behavioral context beyond the annotation, though it does not detail the generation algorithm or potential limitations.

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

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

Three sentences with minimal waste: first sentence states purpose, second provides illustrative examples, third adds a provenance guarantee. Highly front-loaded and efficient.

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