Colour Memory

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

The description discloses the behavioral traits of returning contrast ratios and pass/fail grades, and the readOnlyHint annotation confirms it is a read-only operation. No contradictions are present. The description adds value by specifying WCAG 2.1 version and the grading system, 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 sentence of 18 words, highly efficient and front-loaded. Every word contributes to the purpose, with no redundancy or filler.

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

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

Given the tool's simplicity (2 parameters, output schema exists), the description is complete. It covers the core functionality without needing elaboration on return values, as the output schema handles that.

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

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

Schema coverage is 100%, and the description mentions 'foreground hex' and 'background' without adding new meaning beyond the schema descriptions. The baseline of 3 is appropriate as the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool returns WCAG 2.1 contrast ratios and AA/AAA pass/fail grades for a foreground hex against a background. The verb 'Return' is specific, and the resource (contrast ratios and grades) is well-defined, distinguishing it from sibling tools like accessibility_font or accessibility_matrix.

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 checking contrast accessibility, but does not explicitly state when to use this tool versus alternatives like accessibility_rules or accessibility_matrix. No guidance on when not to use it or prerequisites is provided, so the usage context is unclear despite the sibling list.

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

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

Annotations already indicate readOnlyHint=true. The description adds behavioral context: ranking by contrast ratio, providing WCAG grades, and specific recommendations for body text, large text, and UI components. This goes beyond annotations 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 a single, well-structured sentence that front-loads key information: inputs and outputs. Every word is meaningful and no redundancy exists.

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

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

The tool has an output schema (not shown but indicated), so return values need not be detailed. Inputs are fully covered, and the description covers the ranking and recommendations. Minor gaps remain (e.g., no mention of error handling or edge cases), but completeness is high for a straightforward tool.

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

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

Schema description coverage is 100%, with both 'background' and 'palette' described. The description adds context (e.g., ranking output) but does not significantly extend understanding of the parameters themselves 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 identifies the tool's purpose: ranking candidate foreground colors by contrast ratio against a background, with WCAG grades and recommendations. It specifies the verb 'return' and the resource 'foreground colours', distinguishing it from sibling tools like accessibility_check or colour_compare.

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

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

The description implies usage context (e.g., choosing accessible text/UI colors) but does not explicitly state when to use this tool versus alternatives or mention prerequisites. It provides clear inputs and outputs, aiding selection, but lacks explicit when-to-use guidance.

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

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

With readOnlyHint: true annotations, the description adds value by specifying the output includes contrast ratios, AA/AAA grades, and a summary. No contradictions. It does not describe side effects, but since the tool is read-only, this is acceptable.

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 key action and purpose, and no unnecessary words. It is concise and informative.

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

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

Given the tool has an output schema, the description need not detail return format. It adequately summarizes the function. No missing critical information; it covers purpose and usage well.

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

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

Schema description coverage is 100% for the single parameter, with an example. The main description does not add additional parameter details beyond what the schema provides, so baseline is appropriate.

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

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

The description clearly states it accepts a palette array and returns a matrix of contrast checks for each foreground/background combination, with pass/fail grades. It explicitly distinguishes from sibling tool accessibility_check by suggesting this tool for palettes.

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

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

It provides explicit guidance: 'Use this instead of calling accessibility_check multiple times for a palette.' This clearly indicates when to use it. It does not mention when not to use it, but the context is sufficiently clear from the description and sibling list.

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

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

Annotations already provide readOnlyHint: true, so the safe read nature is known. The description adds valuable behavioral traits: it is deterministic and incurs no LLM cost. However, it does not disclose other aspects like potential data size constraints or processing time. Overall, the description adds useful context beyond annotations.

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

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

The description is extremely concise: two sentences that cover purpose, outputs, and key behavioral notes. It is front-loaded with the most critical information (what it does and returns) and wastes no words. 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?

For a tool with one parameter, full schema coverage, an output schema, and read-only annotations, the description is fairly complete. It explains the transformation and the outputs. However, it does not explicitly mention that the input palette should be a WCAG matrix (which might require a prior tool call), so an agent may need additional context. Still, it is sufficient for a competent 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 input schema already has 100% coverage with a description for the only parameter ('Array of hex values'). The tool description mentions 'palette' in the context of conversion, but does not add any new semantic meaning or constraints beyond the schema. Hence, it meets the baseline but adds no 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's purpose: converting a palette WCAG matrix into actionable design-system rules. It specifies the exact outputs (safe pairs, AA-only pairs, etc.), and the verb 'Convert' plus resource 'palette WCAG matrix' precisely defines the action. The mention of 'Deterministic, no LLM cost' further clarifies its identity among sibling tools.

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

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

The description lacks explicit guidance on when to use this tool versus alternatives. It implies that a WCAG matrix is needed as input, but does not mention prerequisites, exclusions, or reference sibling tools like accessibility_matrix. An agent would have to infer usage context from the purpose alone.

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. The description adds the specific model name and the fact that three hex values are returned, but does not disclose additional behavioral traits such as accuracy assumptions or limitations. Since annotations cover the safety profile, the description provides minor extra context.

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

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

One sentence, front-loaded with the action, efficiently states the purpose and method. No unnecessary words or redundancy.

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

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

Given the simple input and existence of an output schema, the description sufficiently explains what the tool does and what it returns. The mention of the model and three types provides enough context for an agent to understand the tool's functionality.

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

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

Schema coverage is 100% with a clear description for hex_val. The description does not add any new 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 clearly states the tool's purpose: returns simulated hex values for three types of color blindness using a specific model. It uses a specific verb ('Return') and resource ('simulated hex values'), and distinguishes from sibling tools like accessibility_check by specifying the simulation model.

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

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

No explicit guidance on when to use this tool versus alternatives. Among siblings like accessibility_check or colour_compare, the description does not mention when to use simulation over other accessibility or color tools. Usage is only implicitly derived from the purpose.

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, meaning no mutation. The description confirms it 'fetches' and 'produces' data without modifying anything. This alignment is clear. It adds context about the output components, which complements the annotation. No contradictions noted.

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 reasonably concise given the complexity of the output. It front-loads the main purpose and then lists outputs. The example is helpful. Minor improvement would be slightly more compact listing of components, but 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 8 parameters and an output schema, the description covers all key aspects: what it produces, supported models, parameter roles, and example. It doesn't explain the output schema structure but that is provided separately. Adequate for a high-complexity 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 all parameters described. The description adds value by explaining the interplay of parameters, e.g., locked_palette overrides archive query, and palette_size controls number of colours. This extra context elevates the score above the baseline of 3.

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 generates a 'complete colour direction package' for another AI, listing all output components (agent brief, tokens, prompts, lighting notes). It also names supported models and provides an explicit example, distinguishing it from sibling tools like palette_generate which are about generating palettes for other purposes.

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

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

The description states 'Use this to make Colour Memory the colour layer for other AI systems' and explains the role of locked_palette to prevent drift. It gives an example usage. While it doesn't explicitly list when not to use it or direct alternatives, the context implies its specific purpose among sibling tools.

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

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

The description explains that the tool returns a fidelity score, dE2000 distance per colour, match quality categories, and an overall verdict. This adds behavioral context beyond the readOnlyHint annotation, which already indicates no side effects. The description does not contradict annotations.

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

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

Three sentences with no wasted words: first states purpose, second describes inputs, third describes outputs and usage. Well-structured and front-loaded.

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

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

Given an output schema exists, the description covers all necessary context: what the tool does, what inputs are needed, what outputs are returned, and when to use it. It is complete for a read-only verification tool with clear inputs.

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

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

The description adds meaning by clarifying that either image_url or image_base64 can be supplied (implied 'or'), and that target_palette comes from agent_brief. Since schema coverage is 100%, baseline is 3; the description provides slight additional clarity and mentions output details, earning a 4.

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

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

The description clearly states the tool's purpose: to verify that an AI-generated image used specific colours from an agent_brief call. The verb 'verify' and resource 'colour fidelity' are specific, and it distinguishes this tool from siblings like colour_compare or colour_verdict by focusing on post-generation verification against a known 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 says 'Use after agent_brief + image generation to close the colour loop,' providing clear context for when to use the tool. It does not list alternatives or exclusions, but the use case is well-defined and distinct from sibling tools.

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

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

Annotation readOnlyHint is consistent. Description adds transparency by confirming 'No Claude call — pure archive data analysis,' and detailing the return structure.

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 efficient, front-loading purpose and key details. No unnecessary words, though could be slightly more streamlined.

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 output schema exists, description fully covers tool purpose, usage, and return details. No gaps for an agent to misinterpret.

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?

Only one parameter with schema description covering 100%. Description examples add marginal value, but schema already provides clear guidance.

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

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

Description clearly states it runs a data quality audit on a named archive, listing specific metrics and outputs. It distinguishes from sibling tools like brand_audit or palette_audit by focusing solely on archive data.

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

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

Explicitly states when to use: before building new archive content or after a batch import. Lacks exclusion criteria or alternatives, but 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?

The description aligns with the readOnlyHint=true annotation by describing a search and generative process, not any mutation. It adds behavioral context by mentioning the archive search and Claude's writing of varied outputs (one-liner, short story, tweet). This extra detail helps the agent understand the tool's non-destructive 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 compact: three sentences plus an example. It front-loads the main action, then details inputs and outputs. Every sentence is informative, with no redundancy. The example efficiently ties everything together.

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

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

The description covers the tool's purpose, inputs, and an example. It references multiple output types (one-liner, short story, tweet) even though an output schema exists (as noted in context). Given the complexity, the description is sufficiently complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, but the description adds significant meaning: it explains the concept input (e.g., 'love'), the optional expected_colour (e.g., 'red') for contradiction, and n_results for search depth. The example further illustrates how parameters combine, making semantics clear 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 'Find the most surprising archive colour for a concept and generate a memorable one-liner subverting the obvious expectation.' This specifies the action (find and generate), the resource (archive colour), and the output (one-liner). It distinguishes itself from sibling tools like archive_search by focusing on subverting expectations and creating creative content.

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

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

The description explicitly says 'Use this for public-facing demos, content, and brand storytelling,' providing clear context. It also includes an example and explains optional parameters. It does not explicitly state when not to use, but the guidance is strong 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, confirming safe read operation. The description adds further behavioral context: returns a coverage matrix with entries, grade, best match, claim strength, and needed source type. No contradictions.

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

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

Three sentences, front-loaded with the main purpose. Every sentence adds value: purpose, what it returns, and when to use it. No redundancy or 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 (implied), the description sufficiently explains the return format. Parameter count is low (2), both covered. The tool's role relative to similar siblings (e.g., 'archive_evidence_gap') is clarified by usage guidelines. Slightly more detail on the output schema could elevate further, but current is 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% (both parameters have descriptions). The description adds meaning by explaining that 'themes' are the list to check and 'archives' are optional search filters, which aligns with the schema. It also provides context on how these parameters relate to the tool's purpose.

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

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

The description specifies a clear verb ('report') and resource ('coverage of themes in the archive'). It explicitly distinguishes itself from siblings like 'archive_report_brief' and 'brief_forensic' by stating its use case ('before building' these).

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

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

The description explicitly states when to use this tool: 'before building an archive_report_brief or brief_forensic.' It also explains the benefit: 'prevents building beautiful reports that quietly ignore half the brief.' No explicit when-not, but the 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?

Goes well beyond the readOnlyHint annotation by detailing specific checks (date vs period, modern archives), risk levels, and safe/unsafe phrasing outputs. Adds meaningful context about the tool's analytical 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?

Compact (~100 words), front-loaded with purpose, includes an illustrative example, and no redundant sentences. Every sentence contributes 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 complexity (4 params, one array, output schema exists), the description covers input, processing, and output fields fully. Sibling tools exist but the description clearly defines this tool's niche.

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 brief parameter descriptions; the description adds significant semantics by mentioning specific archives and explaining the role of primary_source and archive fields. Baseline 3, credit for extra 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?

Description clearly states the tool checks colour entries for anachronism risk, specifies what it detects (date vs period, modern archives), lists return fields, and distinguishes from sibling audit tools via the example. Strong verb+resource combination.

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

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

Provides clear context that it's essential for historical documents and includes a concrete example, but does not explicitly state when not to use it or mention alternative sibling tools. Close to 5 but misses the when-not aspect.

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 doesn't need to repeat that. The description adds valuable behavioral context: it explains the tool is an 'anti-hallucination endpoint' that turns absence of evidence into a forensic finding, which goes beyond the annotation. No hidden side effects are mentioned, but the description is sufficiently 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?

The description is concise (5 sentences) and well-structured: it starts with the core purpose, then provides an example, and ends with usage domains. Every sentence adds information without redundancy.

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

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

Given the presence of an output schema (not shown but context says true), the description doesn't need to detail return format. It covers all key aspects: input (hex, claim), output (support, missing info, source type, safe wording), and context (anti-hallucination). 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 coverage is 100%, so the description does not need to redundantly explain parameters. It adds value by giving an example mapping inputs (hex #4A535C, proposed claim 'cyanosis in a death chamber') to outputs, clarifying how parameters interact. This exceeds the baseline 3.

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 hex value and a proposed claim, it returns archive support level, missing info, needed source type, and safe agent wording. It explicitly positions itself as the 'anti-hallucination endpoint' and distinguishes from siblings like archive_search by focusing on claim validation rather than general search.

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

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

The description specifies essential workflows (museum, documentary, editorial, legal, forensic) and provides a concrete example, making the use case clear. However, it does not explicitly contrast with similar sibling tools (e.g., archive_coverage_gap) or provide exclusions, so it misses full guidance on when not to use.

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

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

Annotations already mark it as read-only. The description adds value by detailing the structured output fields (claim, evidence type, etc.), but does not disclose additional behavioral traits 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 concise and front-loaded, but listing all return fields adds some verbosity. Overall efficient with minimal 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 a single parameter and an output schema (implied), the description covers the tool's purpose and return values sufficiently. It stands alone among many sibling tools.

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

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

Schema coverage is 100% with examples. The description adds minimal extra meaning beyond 'any named archive colour', so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool explains provenance with explicit separation of fact, derivation, and interpretation, and identifies itself as the 'trust endpoint'. It distinguishes from siblings by emphasizing intellectual honesty about colour data provenance.

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

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

The description indicates the tool is essential for scenarios requiring intellectual honesty about colour provenance, but does not explicitly state when not to use it or compare to alternatives like colour_dna or colour_forensics.

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

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

Annotations declare readOnlyHint=true, indicating no mutation, which aligns with the description of a research package. The description adds that it requires 'two Claude calls total' but does not disclose additional behavioral traits like rate limits or error handling. With annotations already covering safety, the description provides marginal extra value.

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

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

The description is front-loaded with the main purpose and output, then elaborates on inputs and outputs. It is slightly verbose but every sentence adds value, such as listing output components and the number of Claude calls. Could be tightened slightly but remains 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 (7 parameters, output schema present), the description is thorough. It explains the comprehensive output, the number of calls, and when to use it. The existence of an output schema means return values need not be detailed further. The description provides sufficient 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?

Schema description coverage is 100%, so the schema itself documents all parameters. The description provides a high-level context for parameters (e.g., 'themes, archives, audience') but does not add significant new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states it is a 'one-call complete archive research package' that outputs ranked colour cards with full provenance, story order, and other detailed outputs. It names specific input fields and output components, distinguishing it from chaining separate tools.

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

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

The description explicitly advises 'Use this first for any document workflow' and contrasts it with chaining multiple tools, implying it is the primary compound tool. However, it does not specify situations where a simpler tool might be preferred.

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 search nature. Description adds behavioral detail about search scope (full-text across names/notes) and output format options (snippets vs full text via include_full). No contradictions.

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

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

Two tightly written sentences that convey core functionality, search scope, and relationship to sibling tool. 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 7 parameters and an output schema, the description covers purpose, scope, and result customization. It explains the boost parameters and the include_full toggle. Missing details on result ordering or pagination, but the tool is well-documented overall.

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 parameters well. The description adds a summary of search categories (material, cultural reference, etc.) which provides context but does not substantially exceed 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?

Description clearly states it performs full-text keyword search across archive colour names/notes, with specific examples of search categories. It distinguishes from conceptual embedding search, making the tool's unique purpose explicit.

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?

Mentions it complements conceptual embedding search with exact keyword matching, providing context for when to use this tool over alternatives. While it doesn't explicitly state when not to use, the differentiation 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, indicating safe read-only behavior. The description adds value by listing the exact status fields returned, providing more transparency than annotations alone.

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

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

Single sentence, no wasted words, front-loaded with the purpose. Every part is essential and clear.

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

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

Given the tool has no parameters, no complexity, and an output schema exists, the description covers all needed context: it lists all returned fields and implies the tool is for monitoring status.

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 no parameters; schema coverage is 100% (trivially). The description does not need to add parameter details as there are none.

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 live archive status and enumerates specific data points (total colour count, per-archive breakdown, embedding model, search engine state, API version). This clearly distinguishes it from sibling tools like archive_audit, archive_search, etc.

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

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

The description implies the tool is for retrieving status but does not provide explicit guidance on when to use it versus alternatives (e.g., when to use archive_status vs archive_audit or archive_search). No when-not-to-use or alternative mentions.

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

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

Beyond the readOnlyHint annotation, the description adds that the tool is 'Deterministic' and 'No LLM cost,' which are valuable behavioral traits. It also lists the specific outputs produced, aiding agent understanding.

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

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

The description is extremely concise, with two sentences that front-load the purpose and output details. Every sentence adds unique 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 has an output schema, the description appropriately delegates return value details to it. The description covers all key outputs and is complete for an export tool.

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

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

Schema description coverage is 100%, so the schema already provides parameter details. The description does not add extra semantics beyond the schema, but this is acceptable as the schema is comprehensive.

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: it exports a complete brand asset pack with specific outputs like CSS variables, Tailwind config, Figma tokens, etc. It distinguishes itself from siblings (e.g., brand_audit, brand_report) by focusing on final export rather than analysis.

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

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

The description implies usage for final brand delivery ('Everything a brand team needs to ship'). It doesn't explicitly state when not to use or compare to alternatives, but the context of siblings suggests it's for export purposes.

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

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

Annotations already declare readOnlyHint=true, indicating no destructive side effects. The description adds that all data is computed with 'no LLM cost', which is valuable behavioral context. It also details the comprehensive output, further clarifying what the tool does without contradictions.

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

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

The description is three sentences: first states main purpose, second lists outputs, third gives usage notes. Every sentence adds value, no redundancy, and the key action is front-loaded.

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

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

Given the tool's complexity (5 parameters, output schema, annotations), the description covers all needed aspects: purpose, output details, usage recommendation, and relationship to siblings. It is complete without requiring further clarification.

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

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

Schema has 100% coverage with descriptions for all 5 parameters, including defaults and examples. The description reinforces the parameter list but does not add new semantic meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states it performs a 'Complete brand colour intelligence audit', lists specific outputs (colour roles, WCAG matrix, cultural risk, palette verdict, etc.), and distinguishes itself by replacing chaining of separate tools (accessibility_matrix, cultural_risk_assessment, palette_verdict). This provides a precise verb+resource with sibling differentiation.

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

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

The description explicitly recommends passing results to an LLM for written narrative and notes it replaces chaining multiple separate tools. This gives clear when-to-use and when-not-to-use guidance, effectively differentiating from 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 indicate readOnlyHint: true, so the tool is non-destructive. The description adds rich behavioral detail: it returns CIEDE2000 distances, archive context, distinctiveness score, ownership verdict, plain-English summary, and strategic recommendation. No contradictions.

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

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

The description is three sentences: first poses the question, second lists inputs/outputs, third gives usage context. It is front-loaded and free of fluff. Could be slightly tighter but overall 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 (6 parameters, output schema present, annotations present), the description fully addresses purpose, inputs, outputs, and usage scenario. It explains what the outputs mean and when to use. No gaps.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description restates inputs in a sentence ('brand hex, brand name, competitor hexes and names, market, region') but adds only marginal context (e.g., 'hero colour hex'). 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 purpose: assessing whether a brand can own a color against competitors in a market. It lists all inputs and outputs with specific metrics (CIEDE2000, distinctiveness score, ownership verdict), and the name and title align. It distinguishes from sibling tools like colour_metrics by focusing on competitive ownership.

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 advises using this tool before committing to a brand colour in a competitive market and notes it replaces manual competitor palette analysis. While it doesn't specify when not to use (e.g., for non-competitive contexts), the guidance is clear enough for an AI agent.

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

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

Discloses that the tool 'runs entirely internally -- no chained calls, cannot be blocked by agent safety filters', adding behavioral insight beyond the readOnlyHint annotation. This explains how the tool operates internally, which is valuable for an 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?

Description is four sentences long, front-loading the purpose and inputs/outputs efficiently. While it lists many outputs, it remains focused and avoids redundancy. Could be slightly more structured but is still 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's complexity (7 parameters, nested objects, output schema), the description provides a comprehensive list of outputs and operational details (internal execution, no chained calls). With an output schema present, it does not need to detail return values further.

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's parameter list adds no new semantic detail. It repeats input names but doesn't explain formats or constraints beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool produces a 'complete brand colour intelligence report' and lists specific outputs, distinguishing it from chaining multiple individual tools. It uses a specific verb 'report' and resource 'brand colour intelligence', and differentiates from siblings by advising use over separate tools.

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

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

Explicitly says 'Use this instead of chaining colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief separately', providing clear when-to-use guidance. Also notes 'Runs entirely internally' and 'Two Claude calls total', giving concrete usage context.

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

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

Annotations already declare readOnlyHint=true, so the tool is non-destructive. The description adds 'Deterministic. No LLM cost,' which are useful behavioral traits beyond annotations. No contradictions.

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

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

Two concise sentences front-load the core purpose and then list key outputs. Every sentence adds value with zero redundancy or fluff.

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

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

Given the output schema exists, the description does not need to detail return values, but it still summarizes the major outputs. For a complex tool with 5 parameters, the description covers purpose, behavior, and key deliverables adequately.

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

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

Schema coverage is 100% with descriptions for each parameter. The tool description does not add new meaning beyond the schema; it lists outputs but doesn't explain how parameters influence them, so baseline 3 is appropriate.

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

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

The description clearly states it provides a complete brand colour system in one call, listing specific outputs (colour roles, light/dark maps, typography guidance, etc.). This distinguishes it from sibling tools that focus on individual aspects (e.g., accessibility, palette 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 a comprehensive colour system via 'in one call' but does not explicitly state when to use this tool versus alternatives, nor when not to use it. Sibling tools like 'palette_specify' or 'brand_audit' are not contrasted.

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

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

Annotations already indicate readOnlyHint=true. The description adds value by listing the returned data types (hex, archive, provenance, cultural notes), providing context beyond safety info.

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

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

Single sentence, no wasted words. Perfectly concise and front-loaded with purpose.

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

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

Given the tool's simplicity (2 optional params, no required, output schema exists), the description covers all necessary context. No gaps for an agent to use it correctly.

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

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

Schema coverage is 100% with descriptive parameter docs. The description adds no extra meaning beyond the schema, so baseline score of 3 applies.

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

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

The description clearly states it is a lookup tool for a named colour, returning specific fields (hex, archive, provenance, cultural notes). This distinguishes 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?

No explicit guidance on when to use this tool vs alternatives. While the purpose is clear, there are many sibling tools and the description does not provide when-not-to-use or alternative tool references.

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 value by detailing the return information (harmony type, clash warnings, contrast summary, deployment rules), which is not in annotations. No contradiction.

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

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

A single, well-structured sentence that front-loads the core purpose and enumerates returns. Every phrase earns its place 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 output schema exists, the description appropriately summarizes key return elements. It provides sufficient context for an agent to understand when to invoke this tool versus others.

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 both parameters have descriptions. The description's mention of '2-5 hex values' and context list reinforces but does not add substantial new meaning beyond the schema.

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

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

The description uses specific verbs ('assess') and resources ('colours as a combination for a given context'), clearly distinguishing it from sibling tools like colour_compare or colour_harmonies by emphasizing combination assessment across multiple contexts.

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

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

The description implies usage for evaluating colour combinations in UI, data viz, etc., but does not explicitly state when to use this over alternatives or provide exclusion criteria. With 76 sibling tools, more explicit guidance would be beneficial.

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

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

Annotations indicate readOnlyHint=true, which is consistent. The description adds behavioral details beyond annotations, such as the types of comparisons (LRV, chroma, etc.) and cultural context. It does not mention rate limits or auth, but that 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 three sentences, front-loaded with purpose, and every sentence adds value. No wasted words.

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

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

Given the tool's complexity, full schema coverage, annotations, and the presence of an output schema, the description is complete. It covers purpose, outputs, usage, and exclusions.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond what the schema provides for the parameters themselves. It focuses on output and usage.

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

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

The description clearly states the tool performs deep perceptual and semantic comparison between two hex values, listing specific metrics returned. It distinguishes itself from siblings by noting it is not a harmony tool but a decision and reasoning tool.

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

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

The description explicitly advises using the tool when choosing between two colors or explaining why one works better, and clarifies it is not for harmony. While it does not name specific alternative tools, 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?

The description discloses that the tool 'returns warnings, positive associations, and context-dependent readings' and is based on 'documented cultural colour associations, not generalisation.' This adds behavioral context beyond the readOnlyHint annotation, which is already true and consistent. No contradictions.

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

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

The description is concise with three sentences: purpose, output, and usage context. Every sentence adds value, and it is front-loaded with the core action. 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 tool has only three optional parameters and an output schema exists, the description covers the essential aspects. It describes the output type (warnings, associations, market flags) and mentions specific examples. It is 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 description coverage is 100%, so the schema alone documents parameters well. The description provides high-level context (hex vs palette, optional markets) but does not add significant meaning beyond the schema descriptions. Hence, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to assess cultural sensitivity, symbolic weight, regional taboos, etc., for a hex value or palette. It uses specific verbs like 'Score' and identifies the resource (hex/palette). It distinguishes from sibling tools by focusing on cultural risk, setting it apart from other colour tools like accessibility_check or colour_verdict.

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

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

The description explicitly states when to use: 'Use before deploying a colour in a global brand, product, or campaign context.' This provides clear guidance. However, it does not mention alternatives or when not to use, though the sibling list implies other colour 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?

Annotations provide readOnlyHint=true. The description adds that it's 'No Claude call -- pure archive and physics data. Fast and cacheable.' This goes beyond annotations to explain behavior and performance.

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

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

The description is two sentences plus a list of outputs. It is concise, front-loaded, and every part is useful. 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 (returns many attributes) and the presence of an output schema, the description fully covers what the tool does. It explains the input, output list, and notes it's fast and cacheable.

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 parameter 'hex', described as 'Hex colour to fingerprint'. The description reinforces this by giving an example like '#4A2A50' and explaining that it returns many fields. No additional parameter-level semantics 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?

The description clearly states it's a 'Compact semantic fingerprint for any hex colour' and lists all returned attributes. It distinguishes itself from sibling tools like colour_story or colour_namer by emphasizing semantic reasoning without 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 says 'Use when an agent needs to reason about a colour semantically without reading long prose. Ideal for filtering, ranking, or comparing colours.' This gives clear context, though it doesn't explicitly name alternatives or state when not to use.

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

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

Annotations confirm read-only, and the description adds behavioral details: output structure (verdict, risks, actions, light behaviour under three illuminants), reliance on CIEDE2000 and Claude knowledge. There is no contradiction, and the description enhances understanding of the tool's analytical 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 concise (4 sentences) and front-loaded with the main purpose. The output list is informative but not overly verbose. Examples provide clarity without excessive 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?

Given the tool's complexity (5 params, output schema exists), the description adequately covers what the tool does and returns. It explains the backing methodology and provides examples. The existing output schema handles return value details, so the description remains complete without duplication.

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

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

Schema coverage is 100%, but the description adds value through example usages (e.g., 'ultramarine on lime plaster') that implicitly illustrate parameter combinations (hex, substrate, orientation). This contextualizes parameters beyond their schema descriptions.

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

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

The description clearly states the tool's purpose: assessing hex colour safety for physical applications. It lists specific outputs (verdict, risks, actions) and gives concrete examples, making the function distinct. However, it does not explicitly differentiate from similar siblings like colour_cultural_risk or colour_verdict, slightly limiting 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 implies usage for physical application safety checks but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, leaving the agent to infer from context.

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

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

Annotations already indicate readOnlyHint=true, so the agent knows it's a safe read operation. The description adds that it matches to 'named archive colours', implying a dependency on an archive, but does not disclose behavior for missing or invalid hex values. It provides enough context 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?

One sentence, no wasted words. Front-loaded with the main action and result. Every word earns its place.

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

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

The tool is simple, and an output schema exists to document return values. The description covers the core functionality. However, it lacks mention of input validation or the archive-matching process, but overall it is adequate for this complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description lists specific harmony types (complementary, triadic, etc.), which adds meaning beyond the schema's generic 'Harmony types to include'. This clarifies the valid values for the harmony_types parameter.

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

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

Description clearly states the tool returns complementary, triadic, analogous, and split-complementary harmonies matched to named archive colours. The verb 'Return' and specific harmony types make the purpose unambiguous. It distinguishes from siblings like colour_combination by specifying 'harmonies' and 'named archive colours'.

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

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

No guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description only states what it does, leaving the agent without context for selection among many colour-related sibling tools.

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

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

The description adds context beyond the readOnlyHint annotation by explaining the tool uses 'the nearest archive colour's cultural provenance' and generates multiple content types. 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 four sentences, front-loaded with the core capability, and every sentence adds value. No redundant or filler text.

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

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

The description covers purpose, parameters, use cases, and behavioral context. Since an output schema exists (mentioned in context signals), it does not need to explain return values. The description is sufficiently complete for a tool of this complexity.

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

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

The description reinforces parameter meanings with examples (e.g., hex colour example, audience/tone defaults) and provides context about provenance, but the schema already covers 100% of parameters with descriptions. The added value is marginal.

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, story, tweet, image prompt, and follow-up questions for a hex colour, which is specific and useful. However, it does not explicitly distinguish this from sibling tools like colour_story or colour_dna, which might generate similar content.

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

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

The description provides clear use cases: 'make archive colours shareable, generate content, power a public-facing colour chat experience.' It does not explicitly state alternatives or when not to use this tool, but the provided use cases offer sufficient 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 confirms a non-destructive search. However, it does not disclose details like match algorithm or behaviour for invalid input, which is acceptable but adds minimal value.

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

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

Single sentence is highly concise and front-loaded with the key action and scope. No unnecessary words or details.

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?

Despite brevity, the description covers the core purpose for a simple tool with an output schema. It hints at multiple matches via the 'n' parameter, though not explicitly stated in the description itself, but schema compensates.

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% coverage, with descriptions for all three parameters (n, brand, hex_val). The description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Find the nearest named colour' and specifies the resource as commercial paint systems including Farrow and Ball and Little Greene, clearly distinguishing it from sibling tools like colour_compare or colour_combination.

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

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

No guidance on when to use this tool versus alternatives; no when-not or context provided. Agent must infer from the description alone that it is for paint colour matching.

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. The description adds value by disclosing specific illuminants (D65, F11, Illuminant A) and metrics, providing behavioral context 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 that is front-loaded with the core action and efficiently lists metrics. No extraneous words.

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

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

With an output schema available and only one simple parameter, the description adequately covers the tool's function. It lists all main output components and light sources, making it complete for this complexity level.

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 'hex_val'. The description does not add additional parameter semantics beyond the schema. Baseline score of 3 is appropriate.

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

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

The description specifies the tool returns 'perceptual colour metrics' with a concrete list (LRV, chroma, hue angle, warmth classification, illuminant shifts). This clearly distinguishes 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?

No explicit guidance on when to use this tool versus alternatives (e.g., colour_compare for comparison, colour_card for card generation). The purpose is implied but lacks direct when-to-use or when-not-to-use instructions.

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

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

Beyond the readOnlyHint annotation, the description reveals the use of CIE Lab perceptual model, subtractive mixing, and the return of both a hex value and an archive match with cultural context. This adds meaningful behavioral insight 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 brief (three sentences plus an example) with no extraneous information. It front-loads the purpose, then output, then example, making it easy to parse.

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 coverage, the description adequately covers the tool's behavior and usage. It could mention error handling or assumptions (e.g., valid hex ranges), but overall it is complete for an agent selecting 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%, so the description adds no new parameter details beyond naming hex_a, hex_b, and ratio implicitly through the example. The baseline of 3 is appropriate; the description does not compensate further.

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

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

The description clearly states it simulates subtractive mixing of two colours using CIE Lab space, distinct from RGB blending. It specifies the output (mixed hex and archive match) and gives an illustrative example, effectively differentiating from sibling tools like 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 explicitly notes the tool is for subtractive (pigment) mixing as opposed to RGB screen blending, providing clear context. However, it does not explicitly list when not to use or mention alternatives among siblings, though the example and model clarification are helpful.

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 a generate-only tool. The description adds that names are 'archive-verified' and 'grounded in a real archive source', providing behavioral context beyond the annotation. However, it lacks details on rate limits, error handling, or side effects.

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

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

The description is concise at four sentences, with the purpose stated in the first sentence. It efficiently lists styles, grounding, and use case without redundancy or filler.

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

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

Given the output schema exists (as indicated), the description does not need to detail return values. It covers the tool's purpose, styles, and principal use case adequately for a naming tool with 5 parameters, though it could mention typical usage scenarios or examples.

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

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

All 5 parameters have schema descriptions (100% coverage), so the description adds minimal extra meaning. It lists the naming styles, echoing the style parameter, and mentions the core use case, which provides slight context but not substantial new semantics.

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

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

The description clearly states the tool's function: generating archive-verified colour names for hex values, with multiple naming style options. It distinguishes itself from sibling tools by focusing on naming rather than other colour-related functions like comparison, harmony, 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 usage for Shopify product naming, but does not explicitly state when to use this tool over alternatives like ecommerce_namer or other colour tools. No exclusions or conditional guidance 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?

The description adds context beyond the readOnlyHint annotation by mentioning an 'archive-grounded name source' and 'dE2000 distance', which disclose algorithmic behavior. However, it does not detail side effects or limitations.

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

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

The description is concise with two sentences, but the second sentence is somewhat cryptic ('Archive-grounded name source with dE2000 distance'), reducing clarity slightly. It is front-loaded with the core purpose.

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

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

Given the tool has an output schema and is relatively simple, the description covers the main output (list of token formats) and the naming source adequately. It could mention the optional archive filter's effect, but overall it is complete enough.

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

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

Schema coverage is 100%, so the description does not need to add much. It merely repeats 'hex value' and mentions the archive parameter without extra details, so it adds minimal 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 explicitly states the tool returns various developer token formats for a hex value, listing specific formats (CSS variable, kebab-case, etc.). It distinguishes itself from sibling colour tools by focusing on token generation rather than analysis or palette creation.

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

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

The description implies the tool is for generating token formats from a hex value, but it does not explicitly state when to use this tool versus alternatives like colour_namer or colour_variants. No guidance on 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 already declare readOnlyHint=true, so the tool is known to be safe. The description adds that it returns a 'rich narrative' and mentions historical context, which goes beyond the annotation but does not reveal any additional behavioral traits like performance or limitations.

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

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

The description is concise with three sentences. It immediately states the input and output, includes an example, and lists use cases. 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 that the input schema is fully documented, an output schema exists, and there are only two parameters, the description provides enough context for an agent to understand the tool's purpose and when to invoke it. No additional information is needed.

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

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

Schema coverage is 100% with both parameters described in the schema. The description adds an example but does not provide additional semantic information beyond what the schema already has. Baseline score of 3 is appropriate.

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

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

The description specifies exactly what the tool does: given a hex value, it returns a cultural narrative about that color. It clearly states the use cases (image generation prompts, brand storytelling, creative briefs) which helps differentiate it from sibling tools like colour_metrics or colour_combination.

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

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

The description implies when to use the tool (when you need cultural context for a color) and provides an example. While it does not explicitly list alternatives or when not to use, the context of sibling tools makes the purpose clear, and the description is sufficient 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?

The description aligns with the readOnlyHint annotation by describing a composite analysis operation without any destructive actions. It adds behavioral context by detailing the various analyses performed (archive grounding, verdict, brand fit, etc.), beyond what the annotation alone provides.

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 reasonably concise given the tool's complexity, with a clear front-loaded statement of purpose. Each sentence contributes meaningful information, though the list of output fields could be streamlined. Overall, it is well-structured but not perfectly 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?

Given the high complexity (5 parameters, nested objects, and an output schema), the description provides complete coverage. It lists all output fields, gives practical examples for context, and clearly distinguishes the tool from its many siblings. The presence of an output schema also reduces the burden on the description.

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 have schema descriptions, achieving 100% coverage. The description adds value with concrete examples (e.g., 'luxury fragrance brand UK/France/Japan') and clarifies the purpose of nested objects like brand_context and constraints. This goes slightly beyond the schema baseline of 3.

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 defines the tool as the 'flagship commercial endpoint' that combines multiple analyses such as archive grounding, verdict, brand fit, market risk, etc. It specifies input and output fields, distinguishing it from the extensive list of sibling tools which are more specialized.

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

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

The description explicitly states when to use this tool—when a comprehensive colour strategy is needed. It lists the input components (hex, brand_context, constraints, markets, medium) and output fields, implying its role as a one-stop solution. However, it does not explicitly mention when not to use it or suggest 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 declare readOnlyHint=true, and the description aligns by describing a read-only tracing operation. It adds behavioral context (chronological order, cultural path) beyond the annotation, though not specifying output format.

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

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

The description is three sentences plus an example, front-loaded with the core purpose. Every sentence adds value, with no 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 output schema exists and the tool is simple (2 params), the description provides sufficient context: purpose, example, and implied output format. No gaps for typical use.

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

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

Schema coverage is 100% with descriptions for both parameters (hex and tolerance). The description adds no additional parameter meaning beyond the schema; the baseline of 3 is appropriate.

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

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

The description clearly states the tool traces a colour's appearances across cultures and centuries in chronological order. It distinguishes from sibling tools like colour_story or colour_forensics by emphasizing chronological history and cultural journey.

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 historical context ('essential for understanding why a colour carries the weight it does') and provides an example, but does not explicitly state when to avoid this tool or compare to 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 discloses what the tool returns (historical variants, lighter/darker, archive matches, cultural siblings). The annotations already indicate readOnlyHint=true, so the description adds useful detail about output types 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 two sentences: the first defines the tool's actions, the second provides context. Every word is purposeful, no redundancy, and it is front-loaded with the core functionality.

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

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

Given the tool has an output schema, the description need not explain return values. It lists all major output categories (historical, lighter/darker, archive matches, cultural siblings), which is sufficient for a single-parameter tool. 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?

With 100% schema description coverage for the single parameter 'name', the baseline is 3. The description restates 'named archive colour' but adds no meaningful additional context beyond the schema, so it neither improves nor worsens the score.

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

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

The description clearly states the tool returns 'historical variants, lighter and darker versions with archive matches, and cultural siblings' for a named colour. It distinguishes from sibling tools like colour_story or colour_dna by focusing specifically on variants and 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 says it is 'essential for designers exploring around a colour', providing a clear usage context. However, it does not explicitly state when not to use this tool or suggest alternatives, so a perfect score is not warranted.

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 no contradiction. The description adds useful behavioral context: it uses CIEDE2000 archive matching and Claude cultural intelligence, and describes the output components (verdict, strengths, risks, alternatives).

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 (about 6 sentences), front-loaded with the core function, and efficiently uses examples. Every sentence adds value; no fluff.

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

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

Given the tool has an output schema (mentioned in context), the description doesn't need to detail return values. It summarizes the output (verdict, strengths, risks, alternatives) and covers key aspects for a 5-parameter tool with 2 required params. Highly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing concrete examples (e.g., 'luxury hotel brand in Japan') that illustrate how to fill parameters, 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 evaluates a hex colour for a specific use case, market, and medium, and returns a decisive verdict with strengths, risks, and alternatives. It uses specific verbs and resources, distinguishing it from sibling colour tools.

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

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

The description provides clear guidance on when to use the tool (evaluate a single colour for a specific context) and gives examples. However, it does not explicitly differentiate from similar tools like colour_cultural_risk or palette_verdict, so it misses explicit when-not-to-use instructions.

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 tool being a compound query. The description adds context that it is a replacement for chaining multiple read-only tools, without contradicting annotations. A score of 4 reflects that while annotations already indicate read-only nature, the description enriches understanding of the compound 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?

Description is front-loaded with the key concept 'one-call compound tool,' then lists outputs and alternatives. It is a single paragraph of moderate length, with no redundancy. Slightly verbose in listing all sub-tools, but necessary for clarity.

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

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

Given the parameter count (7) and 100% schema coverage, the description provides sufficient context about the tool's purpose, usage, and what it replaces. The existence of an output schema further reduces need to explain return values. The description is complete for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already describes each parameter. The description does not add parameter-level detail beyond listing example values in the function call. However, it mentions that the tool replaces several sub-tools, which indirectly hints at parameter roles. Baseline score of 3 is appropriate.

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

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

Description clearly states it is a 'one-call compound tool' that produces a complete design package from a concept, medium, audience, and constraints. It lists the outputs (historically grounded palette, cultural narrative, etc.) and distinguishes itself from individual tools like query_conceptual or palette_from_concept.

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

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

Explicitly states when to use: 'when an AI agent or user needs a complete, deployable colour direction in a single call.' Also specifies when not to use: 'Not for iterative refinement — use individual tools for that.' Names the sibling tools it replaces, providing clear guidance.

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

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

The description explains that the copy is never generic but grounded in archive provenance, with colour names from nearest archive match. It provides examples. Annotations indicate read-only, which is consistent. No contradictions, and the description adds behavioral context beyond annotations.

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

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

The description is concise (about 100 words), well-structured with input/output listed and examples. Every sentence adds value, and it is front-loaded with the primary purpose.

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

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

Given the presence of an output schema and detailed input schema, the description covers all necessary contextual information: inputs, outputs, unique value, and examples. No gaps remain.

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

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

The input schema has 100% coverage, with descriptions for each parameter. The description adds value by explaining the role of each input (e.g., hex for colour, product type) and providing examples of usage, enriching the schema information.

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

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

The description clearly states the tool generates complete ecommerce product copy for any colour, specifying inputs (hex, product type, tone, channel) and outputs (colour name, titles, descriptions, etc.). It distinguishes itself from siblings like colour_namer or ecommerce_namer by emphasizing archive provenance and full copy 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 indicates this tool is for generating ecommerce copy grounded in archive provenance, but does not explicitly state when not to use it or mention alternatives. However, the context of siblings suggests it is for full copy generation rather than just naming.

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

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

Discloses that every name is archive-sourced, not invented, and includes source citation. Aligns with readOnlyHint annotation; no contradiction. Adds behavioral context beyond annotations.

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

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

Well-structured, front-loads purpose and key details. Slightly verbose but each sentence is informative. Could be trimmed slightly without losing value.

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

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

Covers inputs, outputs, use cases, and value proposition. Does not detail error handling or edge cases like missing matches, but given output schema and annotations, the description is sufficiently complete.

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

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

Schema coverage is 100% with descriptions; the description adds context by explaining output fields and style options. Does not repeat schema but justifies parameter purpose in the workflow.

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

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

The description clearly states the tool generates archive-grounded colour names for up to 40 SKUs, listing inputs and outputs. It distinguishes from siblings like 'colour_namer' by emphasizing archive-sourced names with citations.

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

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

Explicitly lists use cases (paint ranges, candle collections, etc.) and contrasts with invented names, implying when to use. Lacks explicit exclusions or alternative tool recommendations, but the context signals sufficient differentiation.

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

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

Annotations indicate readOnlyHint=true, and the description adds that the image is never stored and processed in memory only, reinforcing safety. It also explains the extraction algorithm, giving sufficient behavioral context beyond the annotation.

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

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

The description is three sentences: main function, algorithm, output details, use cases, and privacy note. Information is front-loaded and each sentence adds value with no repetition or fluff.

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

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

With an output schema present, the description covers input format, algorithm, output contents, use cases, and privacy. Missing details like error handling or size limits are minor given the complexity and existing annotations.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the image format and default n_colours, but does not add significant new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool extracts dominant colours from an image and matches them to named archive entries with provenance. It specifies the algorithm (K-means++, Bradford adaptation) and output details (up to 5 colours with cultural story, RAL, WCAG). The title and description align, and use cases (product photography, interiors, etc.) differentiate it from 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?

The description provides use cases like product photography and mood boards, but does not explicitly state when to avoid this tool or mention sibling alternatives. Usage guidance is implied but not contrasted with other colour or palette 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?

Description discloses important behaviors beyond annotations: photo is never stored, uses Claude Vision, matching algorithm (CIEDE2000), and provides an example output. This adds significant context beyond the readOnlyHint annotation.

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

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

The description is well-structured and informative with no redundancy. It is slightly long but every sentence adds value. Could be tightened slightly, but overall 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 (seasonal analysis, palette with provenance), the description provides sufficient context and an example. The return values are covered by an output schema, so the description does not need to detail them.

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 description adds extra value like specifying that the face should be in natural light, which is not in the schema. This goes beyond the baseline 3 for high 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 specifies the action (upload portrait photo), output (full personal colour analysis with seasonal type, depth, undertone, curated palette), and distinguishes itself from sibling tools like image_palette and colour_analysis by emphasizing personal analysis and historical provenance.

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

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

The description clearly states the use case (personal colour analysis from a portrait) but does not explicitly list alternatives or when not to use. It implies usage context but lacks explicit guidance compared to high-quality examples.

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

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

Annotations indicate readOnlyHint=true, and the description adds rich behavioral context: explains the scoring metric, input format (list with fields), and output components (score, origin, function, etc.). 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 informative and well-structured, starting with the metric definition and followed by examples and use cases. It could be slightly shorter but remains 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 and the presence of an output schema, the description provides complete context: inputs, outputs, usage scenarios, and the metric's significance. No gaps.

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

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

Schema coverage is 100% with descriptions. The description adds meaning by specifying expected fields (name, hex, archive, source, notes) and output details, going 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: scoring alignment between material origin and social consequence. It provides specific values (1.00, 0.80, 0.50) and distinguishes itself from palette generators, making 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 lists use cases: investigative reports, forensic briefs, museum content, editorial PDFs. It does not specify when not to use or mention alternatives, but the context is clear and actionable.

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

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

Annotations indicate readOnlyHint=true, which aligns with the generation nature. The description details the full behavioral output (scheme, paint matches, light advice, etc.), adding significant value 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 informative but somewhat verbose. It front-loads the main action and lists outputs clearly, but could be trimmed without losing value.

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

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

Given the tool's complexity and the presence of an output schema, the description thoroughly explains what the tool returns. It covers all parameters, gives examples, and mentions an alternative tool, making it contextually 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?

With 100% schema coverage, the description still adds meaning: it explains the concept parameter as 'room concept or brief', notes orientation affects light advice, and provides example values. This adds semantic richness beyond the schema defaults.

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

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

The description clearly states the tool generates a complete interior colour specification from a concept or brief, listing specific outputs like scheme, assignments, paint matches, light behavior, accessibility, and rationale. It differentiates from siblings by directing to a PDF tool for downloadable output.

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

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

The description provides examples of inputs and mentions an alternative tool for PDF output. It implicitly defines when to use it, but lacks explicit exclusions or when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint=true. The description adds behavioral context beyond annotations: it is deterministic and incurs no LLM cost, which is valuable for an agent selecting tools.

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-loading the core purpose in the first sentence. Every sentence adds value: returns, usage, and 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?

Given the presence of an output schema (not shown), the description does not need to detail return values. It covers purpose, usage, and behavior completely 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?

There are no parameters, so the description does not need to explain them. The schema coverage is 100% by default, and the description adds no misleading information. Baseline 4 is appropriate.

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

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

The description clearly states the tool returns a live inventory of active endpoints and MCP tools, which is a specific verb-resource pair. It distinguishes itself from siblings as a meta-discovery tool.

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

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

The description explicitly advises using this tool first to discover API capabilities before making calls, providing clear when-to-use guidance. It does not mention when not to use or alternatives, but the context makes it unique.

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

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

Annotations already declare readOnlyHint=true, confirming no side effects. The description adds valuable behavioral context: it is 'deterministic, no LLM cost', and lists what scores and outputs are returned (score, grade, fix list). This goes beyond annotations to inform the agent of runtime 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 concise (three sentences) with front-loaded key information: purpose, scoring dimensions, outputs, and usage context. Every sentence adds value with no redundancy or unnecessary details.

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

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

The description covers the tool's purpose, inputs, scoring areas, and outputs (score, grade, fix list). It references the output schema implicitly. However, it does not detail the output schema structure or any edge cases (e.g., empty palette). Given an output schema exists, this is still 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% with each parameter having a description (e.g., palette: 'Hex values to audit'). The description adds no further parameter semantics beyond what the schema provides. Since baseline is 3 for high coverage, this score 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's a 'Full palette quality audit' and enumerates specific scoring dimensions (accessibility, cultural risk, tonal balance, colour diversity, archive naming strength) and outputs (score 0-100, grade, fix list). It distinguishes from siblings by branding it as an 'enterprise quality gate' and specifying 'use before shipping any 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 advises usage 'before shipping any palette' and notes it's deterministic with no LLM cost, providing a clear use case. However, it does not explicitly mention when not to use this tool or suggest alternatives among the many sibling audit/check tools, leaving some ambiguity for selection.

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