Colour Memory

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

Annotations already indicate readOnlyHint=true, consistent with a read operation. Description adds that it returns contrast ratios and pass/fail grades, but no further 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?

Single sentence, no fluff, front-loaded with key functionality. 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?

With output schema present, description adequately covers return values (contrast ratios, grades). Parameter count is low and simple. Nearly complete; minor gap in not specifying whether result includes both AA and AAA or just one.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds only minimal context ('foreground hex', 'background hex with default'), not exceeding what the schema provides.

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

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

Clearly states it returns WCAG 2.1 contrast ratios and AA/AAA pass/fail grades for a foreground hex against a background, distinguishing 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?

Implied usage for checking specific color contrast, but no explicit when-to-use or alternatives provided. Sibling tools exist but not differentiated in description.

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

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

The annotations indicate readOnlyHint: true, and the description is consistent with a read-only operation. Beyond annotations, the description specifies that the tool ranks candidates by contrast ratio, provides WCAG grades, and gives recommendations for different text/component types. This adds behavioral context (e.g., ranking, specific output types) that annotations alone do not 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 a single, well-structured sentence that presents the input, action, and output clearly. Every word is functional, with no redundancy or fluff. It is front-loaded with the key concept (ranking by contrast) and specifics.

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 (referenced in context signals), the description sufficiently covers what the tool does without needing to detail return format. It explains the inputs and the nature of the output (ranked with WCAG grades and recommendations), which is complete for an agent to understand its purpose.

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

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

Schema description coverage is 100%, with both 'background' and 'palette' having clear descriptions. The tool description reinforces that these are used for ranking and WCAG grading but does not add semantic details beyond what is already in 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's purpose: given a background hex and palette of foreground candidates, it returns them ranked by contrast ratio with WCAG grades and specific recommendations for body text, large text, and UI components. This is a specific verb+resource combination that distinguishes 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 for accessibility contrast analysis but does not explicitly state when to use this tool versus alternatives like accessibility_check or colour_metrics. No exclusions or alternative recommendations are provided, leaving the agent to infer context from the name and description.

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

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

Annotations already declare readOnlyHint=true. The description adds that the tool computes all combinations with contrast ratios and grades, which is useful behavioral context. No contradictions. It doesn't discuss rate limits or authorization, but the read-only nature is sufficient.

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 states what it does, the second provides usage guidance. No extraneous information, well-front-loaded, and every sentence adds value.

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

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

Given the tool has one parameter and an output schema exists, the description sufficiently covers input and output behavior. It explains that it returns grades and a summary. Could mention output format details, but output schema handles that. Adequate for an agent.

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

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

Schema description coverage is 100% with an example hex array. The tool description does not add additional semantics beyond what the schema provides. Baseline 3 is appropriate as schema covers the parameter adequately.

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 accepts a palette array and returns contrast ratios with pass/fail grades for all foreground/background combinations. It also distinguishes from sibling tool 'accessibility_check' by advising to use this for palettes instead of multiple calls.

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

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

The description explicitly says 'Use this instead of calling accessibility_check multiple times for a palette,' providing clear when-to-use guidance relative to a specific alternative. It does not mention when not to use or exclusions, 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?

Annotations already declare readOnlyHint=true. Description adds that the tool is deterministic and has no LLM cost, which is helpful for performance awareness. It also lists output types. However, it does not disclose any potential limitations or side effects beyond being read-only, which is acceptable given the annotation. The added context is moderate.

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

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

Two sentences, each carrying weight: first defines purpose and outputs, second adds performance characteristics. No redundant information, front-loaded with key action. Every sentence earns its place.

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

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

Given the tool has one simple parameter and an output schema exists, the description provides a good overview of what it returns. It also mentions determinism and cost. Could be slightly improved by noting error handling or input constraints, but overall it is complete enough 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?

Only one parameter 'palette' with schema description 'Array of hex values'. Schema coverage is 100%, so baseline is 3. Description mentions 'palette WCAG matrix' which loosely ties to the parameter but does not add detailed constraints or format expectations beyond what the schema provides.

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

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

Description clearly states it converts a palette WCAG matrix into actionable design-system rules, listing specific output types (safe pairs, AA-only, etc.). The verb 'Convert' and resource 'palette WCAG matrix' are precise, and the tool is well-distinguished from siblings like accessibility_check or accessibility_simulate by its focus on generating rules from a 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?

No explicit guidance on when to use this tool versus alternatives like accessibility_check or accessibility_matrix. The description implies it is used when you have a palette and want usage rules, but it does not explain when to prefer this over checking individual items or simulating, nor does it mention excluded scenarios 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 indicate readOnlyHint=true, meaning no side effects. The description adds value by specifying the exact output (hex values for three CVD types) and the algorithm used (Brettel-Vienot-Mollon model), which is beyond the annotations.

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

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

The description is a single sentence that precisely conveys the tool's purpose and output. Every word is necessary, there is no redundancy or clutter.

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

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

Given the tool's simplicity (one parameter, output schema present), the description is fully adequate. It tells the model what input is expected and what output (simulated hex values) will be returned, including the specific vision deficiencies and the model used.

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

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

The schema already describes the 'hex_val' parameter with an example. The description does not add additional meaning or constraints beyond what the schema provides. Schema coverage is 100%, 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 it returns simulated hex values for three specific color vision deficiencies (protanopia, deuteranopia, tritanopia) using the Brettel-Vienot-Mollon model. This distinguishes it from sibling tools like accessibility_check which evaluate contrast, and other color simulation tools.

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

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

The description implies the tool is used to simulate color blindness by returning hex values, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., for checking color accessibility, use accessibility_check). 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?

The description discloses the tool's behavior: it fetches a historically grounded archive palette and produces multiple outputs. The readOnlyHint annotation aligns, as the tool only reads and generates, not writes. The description adds context about the workflow and supported models, going beyond the annotation.

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

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

The description is concise yet comprehensive, starting with the core purpose followed by specific outputs and examples. Every sentence adds value, avoiding fluff. The structured format (outputs listed, models enumerated) aids quick comprehension.

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 need not detail return values, but it effectively lists what the tool produces. Given the complexity (8 parameters, 2 required), the description covers the workflow and optional overrides (archive, style_notes, locked_palette), leaving little ambiguity for an AI agent.

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

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

All 8 parameters are described in the schema (100% coverage), so baseline is 3. The description adds value by explaining the locked_palette parameter's exclusive behavior and providing example values (e.g., 'luxury hotel bedroom' for task). It compensates for schema description brevity with contextual examples.

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

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

The description clearly states the tool's purpose: generating a complete colour direction package for another AI agent or image generation model. It lists specific outputs (agent brief, colour tokens, prompts, lighting notes) and provides examples, distinguishing it from sibling tools that focus on palette generation or direct queries.

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

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

The description explicitly says 'Use this to make Colour Memory the colour layer for other AI systems,' indicating when to use. While it doesn't explicitly exclude alternatives, the context among siblings suggests this tool is specialized for cross-system colour direction. A brief exclusion note (e.g., 'not for direct palette extraction') would enhance clarity.

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 that the tool performs analysis and returns numerical scores and verdicts. Annotations show readOnlyHint=true, consistent with no state modification. Adds behavioral context beyond annotations by specifying what the analysis yields.

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 3-4 sentences, front-loaded with purpose, then lists inputs and outputs, and ends with usage guidance. Every sentence adds unique value with no redundancy.

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

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

Given the tool's complexity (colour fidelity analysis) and the presence of an output schema, the description fully covers inputs, outputs, and workflow context. 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?

All three parameters are described in the schema with 100% coverage. Description adds value by specifying that image_url and image_base64 are alternative ways to supply the image, and target_palette should be hex values from agent_brief.

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 verifies colour fidelity of AI-generated images using a palette from agent_brief. It specifies inputs (image URL/base64, target palette) and outputs (fidelity score, distances, match qualities, verdict). Distinguishes from siblings by focusing on AI generation verification and linking to agent_brief workflow.

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 after agent_brief + image generation to close the colour loop', indicating when to use. Does not list alternatives, but the context of siblings (many colour tools) makes the usage scenario 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?

Description adds context beyond the readOnlyHint annotation by stating it's pure archive data analysis and detailing the audit outputs. 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 concise at two sentences, front-loaded with the main action, and efficiently covers purpose, returns, and use cases without extraneous words.

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

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

Given the single parameter, readOnlyHint annotation, and presence of output schema, the description provides complete context about the audit's scope and contents.

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

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

Schema has 100% coverage for the single parameter; description adds examples of valid archive names (e.g., 'British', 'Tingry'), which enhances understanding beyond the schema definition.

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 runs a data quality audit on any named archive, listing specific returns (entry count, health score, grade, issue counts) and distinguishes from siblings by noting it's pure data analysis without a Claude call.

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

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

Provides explicit usage scenarios: before building new archive content to establish a baseline or after batch import to verify data quality. However, lacks explicit exclusions or alternatives.

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

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

The description discloses that the tool finds an unexpected color and generates a one-liner, short story, and tweet. Annotations already declare readOnlyHint=true, and the description adds context about the creative output 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 moderately concise with front-loaded purpose. It includes an example and usage guidance, but every sentence contributes value. Could be slightly more terse.

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

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

Given the tool's complexity (3 parameters, no enums, optional params, with output schema), the description explains the concept fully, including the example and the role of each parameter. The output schema covers return details, so no gap.

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

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

Schema description coverage is 100%, but the tool description adds significant meaning by explaining the purpose of each parameter in context, including the example 'love + red'. This goes beyond the schema's field 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 states the specific verb 'find' and resource 'archive colour', and clearly distinguishes from sibling tools by focusing on creative subversion with examples like 'love + red returns Shakespeare's dark green'. It is not a tautology.

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

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

The description includes explicit usage guidance: 'Use this for public-facing demos, content, and brand storytelling.' It does not, however, explicitly state when not to use it or compare to alternatives, but the context implies its niche.

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 agent knows it's a safe read operation. The description adds valuable behavioral context: it returns a coverage matrix with grades, best match, and source type needs. It also warns about the risk of ignoring gaps, which provides practical behavioral insight beyond what annotations convey.

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, each serving a distinct purpose: the first states the core functionality and output, the second provides usage context and a warning. No extraneous information, perfectly front-loaded with the key action.

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

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

Given the presence of an output schema (context signals indicate 'Has output schema: true'), the description does not need to detail return values but still summarizes the output effectively (coverage matrix with entries, grades, best match, source type needs). It covers purpose, usage, and outcome well. Minor gap: no mention of error handling or limits, but not critical for this tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds an example for the 'themes' parameter ('e.g. ['opium', 'gin', 'gambling', 'racing']') which clarifies usage. The 'archives' parameter is mentioned as optional, consistent with the schema. No additional semantic depth is added beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool reports which themes are well-evidenced or under-evidenced in an archive, using specific verbs ('report', 'returns') and resource ('coverage matrix'). It distinguishes from sibling tools like 'archive_report_brief' by explicitly advising to use it before building such reports, preventing incomplete outputs.

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

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

The description provides explicit when-to-use guidance: 'Use this BEFORE building an archive_report_brief or brief_forensic to know where the evidence is strong and where gaps will appear.' It also explains the consequence of not using it ('prevents building beautiful reports that quietly ignore half the brief'), effectively telling the agent when to prefer this tool over alternatives.

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

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

Annotations declare readOnlyHint=true, and the description does not contradict this. Description adds behavioral details such as returning period_relevance score, safe/unsafe phrasing, and the logic for checking modern archives, which goes beyond the basic 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?

Description is a single paragraph that front-loads the purpose and immediately lists key capabilities and outputs. It is concise but could be slightly more structured (e.g., bullet points) for easier parsing.

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 explains what the tool does, what it returns (listed: anachronism_risk, period_relevance, safe_phrasing, unsafe_phrasing), and provides a usage example. Given the tool's complexity and that it has an output schema, 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 description coverage is 100%, so the description does not need to add parameter-level details. It provides context for the overall operation but does not enhance parameter semantics beyond what the schema already provides.

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

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

Description clearly states the tool checks colour entries for anachronism risk, detecting source date outside period, modern archives, and returns scores and phrasing. It distinguishes from sibling tools like archive_audit or colour_cultural_risk by focusing specifically on anachronism detection with concrete output fields.

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 a concrete example ('prevents a 2011 Jockey Club racing silk registration being presented as Georgian evidence') that illustrates when to use the tool. Does not explicitly state when not to use or suggest alternatives, but context is clear enough for an agent.

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

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

Annotations only indicate readOnlyHint: true. The description adds substantial behavioral context: it returns multiple structured outputs (support level, missing info, source type, safe wording) and frames the tool as an anti-hallucination endpoint, 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 brief (3-4 sentences) and well-structured: it opens with the core operation, explains the anti-hallucination framing, provides a concrete example, and lists target workflows. Every sentence is purposeful.

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

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

Given the presence of an output schema (which documents return values), the description covers inputs, outputs, purpose, example, and use cases. It could mention error handling or edge cases, but overall it provides sufficient context for agent invocation.

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

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

All parameters are described in the schema (100% coverage). The description adds value by showing how parameters combine in an example (hex #4A535C + proposed claim 'cyanosis in a death chamber'), demonstrating the intended use case and output.

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

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

The description clearly states the tool's function: given a hex value and a proposed claim, it returns archive support, missing info, source needed, and safe wording. It uniquely positions this as an anti-hallucination endpoint, distinguishing it from sibling tools like archive_search or archive_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 fact-checking claims against an archive, especially in museum, documentary, editorial, legal, and forensic workflows. It does not explicitly list alternatives or when not to use, but the context is clear enough for an agent to infer appropriate scenarios.

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

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

Annotations declare readOnlyHint=true, and the description adds value by detailing the output structure (claim, evidence type, source specificity, etc.) and framing it as a trust endpoint, which is consistent.

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

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

The description is three sentences, front-loaded with the key purpose and differentiation, 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?

For a single-parameter tool with an output schema, the description covers what it does, how it works, and why it matters, making it fully contextual.

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

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

Schema description coverage is 100% with a clear example, and the description adds context about the tool's purpose. However, no additional parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool explains provenance of a named archive colour, with explicit separation of historical fact, hex derivation, and cultural interpretation. It distinguishes itself from siblings by calling itself the 'trust endpoint' that answers 'how do you know this?'

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

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

The description provides clear context that this is essential for intellectual honesty about colour data provenance, but does not explicitly state when not to use or name specific alternatives among siblings.

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

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

Annotations indicate readOnlyHint true, and the description adds behavioral context such as 'Two Claude calls total' and details of the output (ranked colour cards with provenance, confidence flags, etc.), 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 front-loaded with the main purpose and lists many outputs, but is somewhat lengthy. It earns its sentences, though could be slightly more concise 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 (7 parameters, 1 required, rich output), the description covers inputs, outputs, and usage context thoroughly. An output schema exists, so return values are not needed in 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?

Schema description coverage is 100%, so the description adds little beyond summarizing inputs (title, audience, themes, etc.) in a narrative form. 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 is a 'one-call complete archive research package' for documents, PDFs, editorial briefs, listing specific inputs and outputs. It distinguishes itself from sibling tools by being the endpoint for document workflows, replacing chaining of multiple 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 states 'Use this first for any document workflow' and mentions it replaces chaining archive_search, get_colour_card, cliche_breaker, and agent_brief, providing clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, so the tool's safety profile is clear. The description adds the scope of search (full-text, across colours and notes) but does not disclose additional behavioral aspects like pagination or rate limits, which is acceptable given annotations.

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

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

The description is three sentences, front-loaded with the main action ('Full-text keyword search'), and each sentence adds meaningful information without waste.

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

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

Given 7 parameters with full schema description, an output schema, and read-only annotations, the description adequately covers what the tool does and when to use it. It could mention result handling, but the output schema likely covers that.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add any parameter-specific details beyond what the schema already provides, so no extra value is contributed.

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 full-text keyword search across archive colour names and notes, listing specific query types (name fragment, material, cultural reference, pigment type, historical period). It explicitly distinguishes itself from conceptual embedding search, fulfilling 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 indicates when to use this tool: when exact keyword matching is needed, complementing conceptual embedding search. It does not explicitly state when not to use it, but the contrast with conceptual search provides clear 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 declare readOnlyHint=true, and the description reinforces this with 'Return live archive status'. It adds specific output context (embedding model, search engine state, API version) beyond the annotation.

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

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

Single sentence, front-loaded with action ('Return live archive status'), and no redundant words. Highly 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 that an output schema exists (not shown), the description sufficiently covers what the tool returns. For a parameterless status tool, it is complete.

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

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

Tool has zero parameters and 100% schema coverage; baseline is 4 for no parameters. Description adds no parameter info, but none is needed.

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 live archive status and lists specific fields (total colour count, per-archive breakdown, etc.), making the purpose clear and distinct from sibling tools like archive_search or archive_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 retrieving overall archive status but does not explicitly state when to use it versus alternatives, nor does it provide 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 provide readOnlyHint=true, and the description adds 'Deterministic. No LLM cost.' which clarifies behavioral traits beyond safety (no cost, predictable output). No contradiction; the description supplements annotations well.

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 concise sentences with no fluff. Front-loaded with key deliverables, followed by succinct behavioral notes. 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?

With 5 parameters, an output schema, and rich annotations, the description is complete enough. It covers purpose, deliverables, and key traits (deterministic, cost-free). No gaps given the supporting structured data.

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 need not repeat parameter details. The description adds high-level context about outputs but does not enhance understanding of individual parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses specific verbs ('Returns') and clearly lists the exact outputs (CSS variables, Tailwind config, Figma tokens JSON, citation cards, Markdown brand guide). It distinguishes itself from sibling tools like palette_export or palette_pdf by emphasizing 'Complete brand asset pack' and 'Everything a brand team needs to ship'.

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

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

The description implies usage (when you need a full brand asset pack) and adds 'Deterministic. No LLM cost.' which helps selection. It does not explicitly state when not to use or name alternatives, but the context of sibling tools provides implicit 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 only provide readOnlyHint=true. The description adds significant behavioral context: it is a pure computation (no LLM cost), returns specific computed data (CSS variables, Tailwind config, production notes), and is a single call. This goes beyond what annotations offer.

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

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

The description is a single paragraph that effectively front-loads the core function and lists key outputs. It is reasonably concise but could benefit from bullet points for the outputs. Overall efficient with no wasted words.

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

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

Given the tool's complexity (5 parameters, output schema, many siblings), the description is complete. It covers purpose, usage, outputs, and differentiation. The presence of an output schema means return values are fully documented elsewhere, so no additional explanation 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 descriptions for all 5 parameters. The description lists the parameters (palette, market, use_case, medium, brand_category) but adds no new semantic detail beyond what the schema already provides. 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 in one call' and lists specific outputs like WCAG matrix, cultural risk, palette verdict. It explicitly distinguishes itself from sibling tools by stating it 'replaces chaining accessibility_matrix + cultural_risk_assessment + palette_verdict separately.'

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

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

The description provides clear context: it is a single call replacing multiple separate tool invocations. It advises passing results to an LLM for narrative, indicating the tool yields structured data. It does not explicitly state when not to use it or mention alternatives beyond the named tools, but the guidance 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 indicate readOnlyHint=true, which the description does not contradict. The description adds behavioral detail by listing the computed outputs (CIEDE2000 distance, distinctiveness score, ownership verdict, etc.), providing transparent expectations beyond the annotation.

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

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

The description is concise (5 sentences) and front-loaded with the core question. Every sentence contributes meaning, and the list of outputs is compact yet 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's complexity (6 parameters, output schema present), the description adequately covers the main scenario and expected results. It does not detail error handling or edge cases, but the presence of an output schema reduces the need for exhaustive 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?

Schema description coverage is 100%, so the input parameters are already well-documented. The description lists the inputs in a natural language form but does not add new constraints or examples beyond what the schema provides.

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

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

The description starts with a clear question 'Can this brand own this colour against these competitors in this market?' which immediately conveys the tool's purpose. It lists specific inputs and outputs, and distinguishes it from siblings by stating it replaces manual colour distance checks and competitor palette 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 explicitly states 'Use before committing to a brand colour in a competitive market,' giving clear context for when to invoke the tool. However, it does not mention when not to use it or suggest alternative tools among the many colour-related 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 declare readOnlyHint=true, indicating a safe read operation. The description adds behavioral context by stating it 'runs entirely internally -- no chained calls, cannot be blocked by agent safety filters,' which goes beyond annotations.

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

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

The description is well-structured with a clear lead sentence, list of inputs/outputs, and usage guidance. It is comprehensive but not excessively verbose for the complexity of the tool.

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

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

Given the tool's complexity (7 parameters, 1 required, nested objects, output schema present), the description covers all essential aspects: inputs, outputs, internal execution, and guidance vs alternatives. No gaps identified.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions key parameters (hex, brand context, markets, medium, product type) but does not add significant new meaning beyond the schema.

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

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

The description clearly states it is a 'complete brand colour intelligence report' and lists many specific outputs (archive anchor, cliche contradiction, etc.). It distinguishes itself from siblings by explicitly saying to use this instead of chaining multiple separate tools.

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

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

The description explicitly says when to use this tool (for a complete report) and when not to (instead of chaining colour_strategy, cliche_breaker, etc.). It also notes that it runs internally with no chained calls and cannot be blocked, providing clear 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?

Beyond the readOnlyHint annotation, the description adds 'Deterministic. No LLM cost.' This gives the agent clear behavioral expectations: it is consistent and does not incur additional LLM token costs. This is valuable information not available in 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?

The description is two sentences long, front-loading the main purpose, and every word adds value. No filler or repetition. It efficiently conveys the tool's comprehensive output and behavioral traits.

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 items, has an output schema), the description provides a thorough list of what is returned. Combined with the schema and annotations, the agent has all necessary information to invoke the tool correctly.

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

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

The input schema already covers all 5 parameters with 100% description coverage. The description does not add meaning beyond what the schema provides (e.g., palette is 'Hex values' but that is already in the schema). Baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states it returns a 'Complete brand colour system' with specific outputs (colour roles, light/dark maps, typography, usage rules, design tokens, citation cards). This verb+resource combination is specific and distinguishes it from sibling tools like 'colour_card' or 'brand_audit', which are more focused.

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

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

The phrase 'in one call' implies it's a comprehensive alternative to using multiple sibling tools. While it doesn't explicitly state when not to use, the context of granular siblings guides appropriate use. Adding a note like 'Use this instead of calling multiple colour/palette tools individually' would reach a 5.

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

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

Annotations already declare readOnlyHint=true. The description adds value by specifying the returned data (hex, archive, provenance, cultural notes), providing behavioral context beyond the annotation. No contradiction.

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

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

A single, front-loaded sentence that efficiently conveys the tool's purpose without extraneous words. Every part earns its place.

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

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

Given the tool's simplicity (2 optional parameters, output schema present, read-only annotation), the description is complete. It covers what the tool does and what it returns, and aligns with the structured data.

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 well-described. The description does not add additional semantics beyond the schema; it only summarizes the tool's purpose. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'look up', the resource 'named colour', and the specific outputs (hex, archive, provenance, cultural notes). It distinguishes this tool from siblings like colour_compare or colour_combination which are for comparisons.

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

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

The description implies usage for retrieving details of a single colour by name, but does not explicitly state when to use this tool versus alternatives like colour_slugs or colour_story. No exclusion guidance is provided.

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

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

The description aligns with readOnlyHint: true by stating 'assess' and returning analytical outputs. It adds transparency by detailing the returned information (harmony, clash, contrast, deployment rules), providing 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?

Two sentences with no wasted words. The first sentence states the core action and scope, the second enumerates outputs. Information is front-loaded and easily scannable.

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 and full parameter coverage, the description is complete. It covers input constraints, usage context, and expected outputs, requiring no additional context for invocation.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description reiterates the colour format (hex) and context list but adds no new semantic information beyond what the schema provides.

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

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

The description uses specific verb 'assess' and resource 'colours as a combination for a given context', clearly distinguishing it from siblings like colour_compare or palette_audit. It lists return types, making the purpose unmistakable.

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 contexts (UI, data viz, fashion, interior, print, branding) and the color range (2-5). It doesn't explicitly state when not to use or alternatives, but the context restriction implies usage boundaries.

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 detailed behavioral traits beyond annotations, including returns of LRV, chroma, hue angle, warmth, CIEDE2000 distance, and cultural context. It aligns with the readOnlyHint annotation, with 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 two meaningful sentences plus a usage guideline and a clarifying line. It is front-loaded with the core purpose and contains no unnecessary words.

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

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

Given the presence of an output schema, the description adequately covers purpose, usage, and behavioral traits. With simple parameters and an output schema, 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 description coverage is 100%, and the parameters (hex_a, hex_b) are straightforward hex values. The description does not add significant meaning beyond the schema, as both schemas already describe the parameters as hex strings.

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 'deep perceptual and semantic comparison' of two hex values, listing specific outputs. It also distinguishes itself from siblings by explicitly stating 'Not a harmony tool' and positioning it as a 'decision and reasoning tool'.

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

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

The description provides explicit usage context: 'Use when choosing between two colours or explaining why one works better than another.' It also excludes a common alternative ('Not a harmony tool'), though it does not name specific 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 annotation indicates readOnlyHint=true, which is consistent. The description adds behavioral context: it returns warnings and positive associations, is based on documented associations (not generalizations), and provides market-specific flags. This goes beyond what annotations alone 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 at four sentences, front-loaded with the main action, and includes usage context. Every sentence adds value without redundancy.

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

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

Given the output schema exists and annotations are present, the description covers all necessary aspects: what the tool does, when to use it, what it returns, and the basis of its analysis. No gaps are evident.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the parameter information (e.g., 'hex', 'markets', 'palette') without adding significant new meaning beyond the schema. No additional semantics are provided.

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

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

The description clearly states the tool assesses a colour or palette for cultural sensitivity, symbolic weight, and regional taboos. It uses a specific verb ('score') and resource ('hex value or palette'), and the purpose is distinct from sibling colour tools like colour_combination or colour_compare.

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

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

The description explicitly states when to use the tool: 'before deploying a colour in a global brand, product, or campaign context.' It does not explicitly mention when not to use or provide alternatives, but the context is clear and adequate 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 important behavioral traits beyond the readOnlyHint annotation: 'Fast and cacheable', 'No Claude call -- pure archive and physics data', and lists specific output components. This gives the agent a clear understanding of performance characteristics and data sources.

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?

Highly concise: the description front-loads the core purpose and output, then adds use-case guidance and performance notes. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema (not shown but referenced), the description covers all necessary context: input, key outputs, use cases, and performance characteristics. It is complete for an agent to select and invoke this tool correctly.

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

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

The input schema has 100% coverage with a clear description of the 'hex' parameter ('Hex colour to fingerprint e.g. '#4A2A50''). The description doesn't add additional semantic meaning beyond the schema, but the baseline of 3 is appropriate as the schema already does the job.

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 a 'Compact semantic fingerprint for any hex colour' and lists specific output attributes (depth, temperature, chroma band, etc.). It distinguishes itself from sibling tools by noting 'No Claude call -- pure archive and physics data', making the purpose distinct and well-defined.

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 agent needs to reason about a colour semantically without reading long prose. Ideal for filtering, ranking, or comparing colours.' While it doesn't explicitly list when not to use or alternatives, the context is clear enough for an agent to differentiate from sibling tools like colour_story or colour_verdict.

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

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

Annotations declare readOnlyHint=true, and the description is consistent, adding context such as return structure (verdict, risks, actions, light behaviour, substrate notes, alternative) and backend methods (CIEDE2000, Claude knowledge). This provides valuable behavioral insights 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 compact: two sentences followed by a return list and examples. It front-loads the purpose and returns. Minor room for tighter phrasing, 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?

For a tool with 5 parameters, existing output schema, and annotations, the description covers the return structure, provides specific examples, and mentions illuminants. It does not detail every parameter or workflow, but suffices for an agent to judge applicability.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it mentions hex and substrate but does not elaborate on use, finish, or orientation. Examples include oriented surfaces but do not clarify parameter usage meaningfully.

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 whether a hex colour can be safely specified for a physical application. It specifies the resource (colour) and action (safety assessment), and distinguishes itself from siblings by focusing on physical application safety rather than colour comparison or metrics.

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 but does not explicitly state when to use this tool versus alternatives like colour_cultural_risk or colour_match_paint. No exclusions or alternative scenarios are mentioned, leaving guidance inferred.

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 that harmonies are 'matched to named archive colours', implying a lookup behavior. However, it does not detail side effects, auth requirements, or rate limits, which are less critical given the read-only nature.

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

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

The description is a single, clear sentence that immediately states the action and scope. It contains no redundant information and is 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 (2 parameters, output schema present) and many siblings, the description provides adequate core functionality but omits details on how 'matching to named archive colours' works or any prerequisites. The output schema likely fills some gaps, but the description could be more self-contained.

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

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

The input schema covers both parameters with descriptions (100% coverage), but the description adds explicit enumeration of harmony types ('complementary, triadic, analogous, and split-complementary'), which is not present in the schema as enums. This significantly aids understanding of 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?

The description uses a specific verb 'Return' and resource 'harmonies' with qualifiers ('complementary, triadic, analogous, and split-complementary' and 'matched to named archive colours'), clearly distinguishing it from sibling colour tools like colour_compare or colour_metrics.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., colour_compare, colour_metrics). The description only states what the tool does, without context for selection or exclusion.

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 states the tool generates content and is backed by cultural provenance, adding context beyond the readOnlyHint 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?

Three sentences, first sentence captures core function, efficient and front-loaded with key information.

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

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

Given the presence of an output schema, the description sufficiently covers the tool's scope and outputs. Missing details like how follow-up questions are derived are likely in the output schema.

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

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

Schema description coverage is 100% so baseline is 3. The description reinforces hex as any colour and audience/tone as tunable, but doesn't add new semantic details beyond the schema.

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

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

The description specifies the exact outputs (hook sentence, three-sentence story, tweet, image prompt, follow-up questions) and the input (any hex colour). It clearly distinguishes the tool from siblings by listing multiple content types.

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

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

Explicit use cases are given: making archive colours shareable, generating content, powering a colour chat. Also mentions tunability by audience and tone, guiding when to adjust parameters.

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

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

Annotations declare readOnlyHint=true, and description aligns with read operation. However, no additional behavioral context is provided beyond the annotation; lacks details on potential limitations or error handling.

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

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

Single sentence with no extraneous information, front-loaded with core action and scope.

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

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

For a simple tool with 3 parameters and output schema present, description covers essential purpose and brands. Missing minor details like default for n, but overall sufficient.

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

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

Input schema has 100% coverage, already describing all three parameters. Description does not add significant meaning beyond mentioning brand options, which are in schema.

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

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

Description clearly states verb 'find' and resource 'nearest named colour in commercial paint systems', specifying the brands Farrow and Ball and Little Greene, distinguishing it from other 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?

Description implies use for commercial paint matching but provides no explicit guidance on when to use this tool vs. alternatives like colour_namer or colour_compare.

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

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

Annotations indicate readOnlyHint=true, and the description adds behavioral details by enumerating the specific metrics and illuminant conditions returned, enhancing transparency without contradiction.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and outputs 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?

For a tool with one parameter, a clear list of outputs, and an existing output schema, the description covers all necessary aspects for an agent to understand the tool's functionality and results.

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

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

Schema coverage is 100% for the single parameter hex_val, which is adequately described in the schema. The description does not add further parameter semantics beyond the schema's description, meeting the baseline.

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

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

The description clearly states the tool's purpose with a specific verb ('Return') and resource ('perceptual colour metrics'), and lists distinct metrics (LRV, chroma, hue angle, etc.) that differentiate it from sibling tools like colour_compare or colour_forensics.

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

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

The description implies usage for obtaining detailed perceptual metrics, but provides no explicit guidance on when to use this tool over alternatives like colour_compare or colour_harmonies. Missing context for selection among many colour siblings.

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

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

The description discloses the perceptual model (CIE Lab subtractive) and behavior (returns mixed hex and nearest archive match with cultural context), complementing the readOnlyHint annotation. It adds value 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 concise (4 sentences), front-loaded with the core purpose, and every sentence adds value: purpose, output, model emphasis, and example. No redundancy or fluff.

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

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

Given the output schema exists and parameters are well-covered in schema, the description sufficiently covers the tool's use case, behavior, and example. It adequately informs an AI agent without missing critical details.

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 describes all 3 parameters fully (100% coverage). The description reinforces the model (CIE Lab) and provides an example, adding context that helps interpret parameter usage, justifying a score above 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 simulates subtractive mixing of two colours in CIE Lab space, distinguishing it from RGB blending. It specifies the output (mixed hex and nearest archive match) and provides a concrete example, making the purpose unambiguous.

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

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

The description implies usage for paint-like mixing (not screen blending) but does not explicitly state when to use this tool versus alternatives like colour_combination or colour_compare. No when-not-to-use or context-specific guidance is provided.

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

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

Annotations already declare readOnlyHint=true, so the description's claim of generating names aligns. However, the description adds minimal behavioral detail beyond the annotation—such as archive dependency or performance—so it carries limited 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 three sentences, front-loading the core action, and contains no redundant or unclear phrasing. Every sentence adds information (action, styles, value prop, use case).

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

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

Given the presence of an output schema, the description adequately covers the tool's purpose and core use case. It could briefly mention that output includes archive sources, but the output schema likely handles that. Overall sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description echoes the style parameter and adds the archive-grounding context, but does not meaningfully supplement parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool generates memorable, archive-verified colour names for any hex value, with explicit style options. It distinguishes from siblings by highlighting the archive grounding and the core Shopify naming use case.

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

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

The description mentions 'the core of the Shopify product naming use case' which implies a primary scenario but does not explicitly state when to use this tool over alternatives like ecommerce_namer or colour_story. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations indicate readOnlyHint=true, and the description adds extensive behavioral context (returns complete truth, includes multiple data categories). No contradictions; description enriches the agent's understanding of what the tool does.

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

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

The description is a single paragraph that efficiently conveys the tool's purpose and scope. It front-loads the main idea and lists categories. Slight density but no unnecessary words; earns a 4.

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 (many output categories), the description covers the major areas (colour science, archive, provenance, physics, cultural reading). An output schema exists, so return details are not needed. Could mention error handling or limits, but overall 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% with clear descriptions per parameter. The description groups parameters conceptually but does not add new details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Canonical single-call colour truth object' that returns everything about a hex value, listing specific categories (colour science, archive anchor, etc.). It also distinguishes from sibling tools by noting it replaces chaining multiple separate tools.

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

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

Explicitly says 'Use this as the foundation call when you need the complete picture' and notes 'Every other tool is built on this data' and 'Replaces chaining... separately', providing clear when-to-use and alternatives.

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

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

Discloses automatic deduplication and max batch size of 20, beyond the readOnlyHint annotation. No contradictions; annotations and description align.

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

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

Two sentences front-load key info (batch, limit, output), then list use cases. Every sentence adds value; no 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?

Output schema exists, reducing need to explain return values. Description covers purpose, constraints, dedup, and usage context completely for a batch tool.

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

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

All parameters (4) have descriptions in schema (100% coverage), so description adds limited extra meaning. Baseline 3 is appropriate.

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

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

Description clearly identifies as batch version of colour_passport, specifies input limit (up to 20 hexes), and lists output content. Distinguishes itself from the single-colour sibling by name and description.

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

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

Explicitly states use cases: multi-colour workflows, Figma palette analysis, or when repeated single calls would be slow. Implies not for single colour queries, guiding appropriate selection.

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

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

Annotations already declare readOnlyHint=true, so description's burden is lower. The description adds useful behavioral context: output is 'archive-grounded' and uses 'dE2000 distance', disclosing naming methodology. No contradictions with annotations.

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

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

Two sentences with focused content. First sentence front-loads purpose and output formats; second adds context. No filler 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?

With an output schema present, the description needn't detail return values. It lists token formats and explains the naming source. However, it doesn't clarify how the optional 'archive' filter affects output or what 'dE2000 distance' means, leaving minor 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%, baseline 3. The description adds meaning by explaining the 'archive' parameter's role via 'archive-grounded name source', and explicitly mentions 'hex value' tying to the required parameter. This exceeds basic schema descriptions.

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

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

The description clearly states the tool returns 'every developer token format for a hex value' and lists specific formats (CSS variable, kebab-case, etc.). This distinguishes it from sibling tools like colour_namer or colour_combination by specifying the exact resource and 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 implies usage for generating token formats from a hex value but provides no explicit guidance on when to use this tool over alternatives (e.g., colour_namer, palette_generate). No 'when not to use' or exclusion criteria are mentioned.

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

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

Annotations indicate readOnlyHint=true, and the description confirms it returns a narrative without side effects. It adds behavioral context by describing the output's richness and scope (cultural journey, history, archive names), which is beyond the structured 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 and an example. It front-loads the core purpose, then provides context and a concrete example. Every sentence adds value without redundancy.

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

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

Given the tool has two parameters with full schema coverage, readOnly annotations, an output schema (not shown but present), and 50+ sibling tools, the description is complete. It explains what the tool does, when to use it, and gives an example, leaving no ambiguity.

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 no extra meaning beyond what the schema provides for the parameters (hex and n_archives). The example illustrates usage but does not enhance semantic 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's purpose: given a hex value, it returns a rich narrative about the colour's cultural journey, history, meanings, and archive names. It distinguishes itself from sibling tools like colour_forensics or colour_cultural_risk by focusing on cultural narrative and archive names.

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

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

The description mentions specific use cases: image generation prompts, brand storytelling, creative briefs. However, it does not explicitly state when not to use this tool or name alternatives, though the context from sibling tools implies differentiation.

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

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

Annotations declare readOnlyHint: true; description aligns by describing evaluation/analysis, not mutation. It provides detailed behavioral context on what the tool combines and returns, adding 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?

Description is thorough but verbose, listing many output fields and examples. It front-loads the main purpose, but could be trimmed to reduce redundancy without losing clarity.

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

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

Given the complexity (5 parameters, nested objects, detailed output schema), the description is exceptionally complete. It covers input, output, and provides multiple concrete use-case examples, ensuring an agent has full context.

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

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

Schema coverage is 100%. Description adds value by summarizing input structure and providing concrete examples of usage (e.g., 'luxury fragrance brand UK/France/Japan'), which helps an agent understand parameter semantics beyond schema definitions.

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

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

Description clearly identifies this as 'The flagship commercial endpoint' and lists all the analyses it combines (archive grounding, verdict, brand fit, etc.), distinguishing it from the many sibling tools. The examples further clarify its scope.

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

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

Description states it is the flagship commercial endpoint for a complete colour strategy, implying it should be used for comprehensive analysis. It lists input requirements and output, but does not explicitly state when to use simpler alternatives or when not to use it.

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

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

Annotations already indicate read-only behavior. The description adds that it returns a dated sequence of archive entries with primary sources, providing useful behavioral context beyond the annotation.

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

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

Two sentences plus an example. Purpose is front-loaded. Every sentence adds value without redundancy.

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

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

Given that an output schema exists (though not shown) and parameters are fully described, the description is complete. It explains what is returned and includes an illustrative example.

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

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

Schema covers both parameters with descriptions. The description adds example usage for 'concept' and mentions default/max for 'n', adding value beyond the schema.

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

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

The description clearly states the tool traces a colour concept's appearances across cultures and centuries chronologically. It specifies the verb 'traces', the resource 'colour concept', and the scope, distinguishing it from sibling tools like colour_story or colour_hooks.

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

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

Explicitly states use cases: historical research, provenance chains, understanding cultural weight. Provides an example with 'indigo'. Though it doesn't explicitly exclude alternatives, the guidance is clear enough.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds value by detailing the specific outputs (historical variants, lighter/darker versions, archive matches, cultural siblings), providing 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 concise at two sentences, no filler. The key information is front-loaded, with the purpose stated first, followed by a use-case justification. Every sentence earns its place.

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

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

Given the presence of an output schema, the description adequately explains the core functionality. It covers the types of results (historical variants, siblings) sufficiently for a simple query tool. Some minor gaps exist (e.g., no mention of limits or error conditions), but overall it is complete.

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

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

Schema coverage is 100%, with the parameter 'name' fully described in the schema. The description reiterates 'for any named archive colour' but does not add new meaning or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: for a named archive colour, it returns historical variants, lighter/darker versions, archive matches, and cultural siblings. The verb 'return' and the specific resources (variants, siblings) make it distinct 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 implies usage for 'designers exploring around a colour' but does not provide explicit guidance on when to use this tool versus alternatives like colour_dna, colour_harmonies, or colour_mix. No exclusion criteria or alternative mentions are given.

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

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

Annotations declare readOnlyHint=true, which is consistent. Description adds transparency about backing by CIEDE2000 and Claude cultural intelligence, and outlines output structure (verdict, strengths, risks, alternatives). No contradiction.

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

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

Concise, front-loaded with main function. Three sentences with examples, no fluff. Well-structured for quick understanding.

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

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

Given 5 parameters (2 required) and existence of output schema, description is complete. Covers input expectations, output format, and supporting technology. 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 baseline 3. Description adds value by explaining parameters like 'use_case' with examples and context (e.g., 'What the colour will be used for'), enhancing meaning beyond schema.

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

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

Description clearly states it evaluates a hex colour for a specific use case, market, and medium, returning a decisive verdict. Distinguishes from siblings by focusing on actionable decision-making with examples.

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 examples of appropriate use cases, implying when to use. Does not explicitly state when not to use, but context from siblings suggests it's for final evaluation rather than exploratory analysis.

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

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

Annotations provide readOnlyHint: true, indicating no side effects. The description adds context that it is a compound tool combining multiple read-only sub-tools, without contradicting the annotation. It clarifies the tool's behavior beyond annotations.

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

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

Single, well-structured paragraph of 4 sentences. Front-loads purpose, then lists outputs and usage guidance. 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 output schema exists and schema coverage is 100%, the description provides sufficient context. It describes outputs, distinguishes from many sibling tools, and is complete for an agent to decide on usage.

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

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

Schema coverage is 100%, so the schema already describes parameters well. The description mentions 'concept, medium, audience, and constraints' but 'audience' is not a parameter; slightly misleading. Does not add significant value beyond schema.

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

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

The description clearly states the tool as a 'One-call compound tool' that produces a complete design package from a concept, and distinguishes it from individual tools like query_conceptual, palette_from_concept, 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?

Explicitly says 'Use when an AI agent or user needs a complete, deployable colour direction in a single call. Not for iterative refinement — use individual tools for that.' Names alternatives (individual tools) and provides clear when-to-use and when-not-to.

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

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

The description adds context beyond the readOnlyHint annotation by explaining that copy is grounded in archive provenance and that colour names come from nearest archive match, not invented. However, it does not detail behavior when inputs are invalid or missing.

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 5 sentences, front-loaded with the core action, and every sentence adds meaningful information: inputs, outputs, unique value proposition, examples, and use cases.

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 the complexity of generating multiple copy pieces, the description covers all key aspects: inputs, outputs, provenance guarantee, examples, and applicability to platforms. The output schema existence further reduces the need to describe return values in 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?

Schema coverage is 100% (baseline 3), but the description adds value by providing examples for product_type and tone, explaining that tone controls copy style, and listing the full output. It also clarifies the purpose of each parameter implicitly.

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 the inputs and outputs. It distinguishes from siblings like ecommerce_namer (which likely only names) by covering full copy generation including SEO, alt text, 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 usage when a full product copy for a colour is needed, but does not explicitly state when to use this tool versus alternatives like ecommerce_namer for just naming or other colour copy tools. No exclusion criteria are given.

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

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

Annotations indicate readOnlyHint=true; description adds that every name is archive-sourced with a primary source citation defendable to stakeholders. No contradictions and provides useful 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?

Concise yet comprehensive: first sentence defines purpose, then input/output, key feature, use cases, and style options. No redundancy; every sentence adds value.

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

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

Given complexity (5 params, output schema exists), the description covers input, output format, archival basis, and usage contexts. Sufficient for an AI agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, and the description adds meaningful context: lists input and output fields, explains style options (geographical, poetic, material, literary, mixed), and clarifies that names are not invented.

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

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

The description clearly states it generates archive-grounded colour names for up to 40 product SKUs, specifying input (hex values, product category, brand name, naming style) and output fields. It distinguishes from siblings like 'colour_namer' by emphasizing archive-sourced, defensible names for commercial 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?

Explicitly lists use cases: paint ranges, candle collections, fashion lines, homeware, cosmetics. However, it does not explicitly state when not to use or name alternatives, though 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?

Annotations already declare readOnlyHint=true, so the description's role in behavioral disclosure is reduced. The description adds context about input requirements (public URL vs image_id) and optional matching, but does not contradict annotations. A 3 reflects adequate addition 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 well-structured with purpose first, then usage guidance. It is 3 sentences but the second is somewhat long, combining multiple points. It is efficient but not maximally concise, earning a 4.

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

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

Given the complexity (7 parameters, nested object, two input methods, optional matching), the description covers essential scenarios. Output schema exists, so return values need no explanation. It also positions the tool among siblings, making it fully informative for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining when to use image_id (after ingest_image), the role of grey_card_hex for white balance, and style_context for cultural naming. This extra context justifies 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 specifies the tool extracts dominant colours from a photograph using a proprietary k-means++ algorithm. It distinguishes from siblings by mentioning ingest_image (for obtaining image_id) and image_brief (using extracted colours), making the tool's unique role evident.

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

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

Explicit guidance is given on when to use this tool versus alternatives: requires either image_url or image_id; if only raw file, call ingest_image first. Also advises using before image_brief. While clear, it doesn't explicitly state when not to use it or provide exhaustive exclusions, so a 4 is appropriate.

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

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

Annotations declare readOnlyHint=true, and the description confirms the tool is a read-only information extraction. It adds behavioral details: extracts dominant colors, matches to archive, suggests product directions, generates a prompt, and returns a swatch URL. 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 several purposeful sentences. It front-loads the compound endpoint purpose, lists key outputs, and provides usage advice. Every sentence adds value without 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 complexity (compound tool with 8 parameters, 0 required, and an output schema), the description covers the main purpose, outputs, and usage tip. It does not detail error handling or constraints, but the output schema exists for return values. Overall sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds marginal value by mentioning style_context usage context, but most parameter descriptions in the schema are already detailed. The description does not significantly enhance parameter meaning beyond the schema.

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

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

The description clearly states it is a compound endpoint that takes one image and produces a full creative brief. It lists specific outputs (colors, archive matches, scene understanding, etc.) and explicitly distinguishes from sibling tools by recommending use instead of chaining palette_extract, palette_analyse, and agent_brief separately.

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

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

The description provides explicit guidance on when to use this tool over alternatives ('Use instead of chaining palette_extract + palette_analyse + agent_brief separately') and includes a tip on passing style_context for coherent archive matching. It does not explicitly state when not to use, 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?

The description adds significant behavioral context beyond the readOnlyHint annotation: the image is processed in memory and never stored, uses K-means++ and Bradford chromatic adaptation, and returns WCAG accessibility data. No contradictions with annotations.

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

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

The description is concise (three sentences) and front-loaded: first sentence states the core function, second adds technical detail, third lists use cases. No unnecessary words.

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

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

Given the presence of an output schema and full parameter coverage, the description is comprehensive: it explains the output contents, technical accuracy, privacy policy, and suitable contexts. 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?

With 100% schema coverage, the description enriches each parameter's meaning: it explains that colours are matched to archive entries, how extraction works, and what metadata is returned (cultural story, RAL standard, WCAG data), going well beyond the terse 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 extracts dominant colours and matches them to named archive entries with cultural provenance. It distinguishes itself from sibling tools like 'colour_namer' and 'palette_generate' by emphasizing archival matching and cultural data.

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

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

The description lists specific use cases (product photography, interior photos, artwork, brand assets, mood boards) and states the image is not stored. However, it does not explicitly mention when to avoid using this tool or compare it to alternatives like other colour extraction tools.

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

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

Annotations already indicate readOnlyHint=true. The description adds valuable behavioral details: uses Claude Vision, matches via CIEDE2000, and explicitly states the photo is never stored. This goes 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 yet informative. It starts with the main action, details outputs, explains the methodology briefly, and provides an example. Every sentence adds value without redundancy.

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

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

Given the tool has an output schema, the description sufficiently explains return values (seasonal type, palette, colours to avoid) and provides an example. It covers the core functionality and context, making it 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 extra meaning: explains that image_url is easier for MCP, specifies requirements for image_base64 (face clearly visible, natural light), and clarifies the optional name parameter. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: upload a portrait photo for personal colour analysis. It specifies the outputs (seasonal type, depth, undertone, curated palette) and uses specific terminology. It distinguishes itself from sibling tools like image_palette by focusing on personal analysis with archive colour matching.

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

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

The description provides clear context for when to use this tool (for personal colour analysis from a photo) and includes an example. However, it does not explicitly state when not to use it or mention alternatives 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?

Annotations indicate readOnlyHint: true, and the description confirms read-only behavior (scoring). The description adds context about the proprietary metric, the scoring rationale, and the confidence output, going beyond the annotation's minimal information.

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: starts with the core metric, then score examples, input/output summary, use cases, and a closing statement. It is slightly verbose but every sentence adds value. The front-loading of the metric is 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 (proprietary metric), the description provides a good level of completeness. It explains the scoring rationale, input/output format, and applications. The output schema exists (though not shown), so the description compensates by listing output fields.

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 2 parameters with 100% description coverage. The description adds value by specifying the expected fields in the entries array ('name, hex, archive, source, notes') and the output fields. This enhances understanding beyond the schema's brief 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: 'Score how tightly the material origin of a colour aligns with its social consequence.' It provides specific score thresholds and examples (e.g., 1.00, 0.80, 0.50), making the metric very clear. It also distinguishes the tool from palette generators, showing uniqueness among siblings.

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

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

The description explicitly lists use cases: 'Use for investigative reports, forensic briefs, museum content, editorial PDFs.' This gives clear context of when to use. It does not explicitly state when not to use or compare to sibling tools, but the listed contexts provide 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?

The description reveals that processing is ephemeral and the image_id is valid for 5 minutes, adding important behavioral context beyond the readOnlyHint:false annotation, which already implies a write operation.

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

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

Two sentences with no extraneous information, front-loaded with the verb and resource. Every sentence earns its place.

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

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

Given 2 parameters (with nested objects), an output schema, and annotations, the description is complete: it explains the upload process, the 5-minute validity, and downstream usage, without needing to repeat return value details.

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, so baseline is 3. The description adds value by explaining the temporal behavior of the returned image_id and clarifying that the image can be provided via file reference or URL.

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

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

The description clearly states the tool uploads an image for ephemeral processing, specifying the resource (Colour Memory) and action. It distinguishes from sibling tools by mentioning the returned image_id is passed to palette_extract or image_brief.

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 for any image over 50 KB' and directs the agent to pass the image_id to specific tools. It gives clear context but does not explicitly mention when not to use or alternatives.

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

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

The description discloses that the tool is generative and produces a specification without side effects. The readOnlyHint annotation already indicates it is read-only, and the description does not contradict this. It adds context about the depth of output and the optional PDF generation, but no additional behavioral concerns are 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 concise and well-structured. It front-loads the core purpose in the first sentence, then details outputs, examples, and a note about the PDF version. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (6 parameters, 1 required) and the presence of an output schema, the description is complete. It covers what the tool does, what inputs are expected, and what outputs are produced, leaving no major gaps for an AI agent to infer.

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 3 is appropriate. The description provides contextual examples and explains the role of parameters like concept and style, but does not add new semantic meaning beyond what the schema already provides for each property.

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

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

The description clearly states the tool's purpose: generating a complete interior colour specification from a concept or brief. It lists specific outputs (60/30/10 assignments, paint matches, light behaviour, etc.) and gives examples of input briefs. It distinguishes itself from sibling tools by mentioning the PDF version and stating it replaces a colour consultation.

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

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

The description explains what inputs are needed (concept, type, style) and provides examples of briefs. It mentions the tool replaces a colour consultation, implying when to use it. However, it does not explicitly state when to avoid it or compare it directly to sibling tools like palette_generate or colour_combination, which could serve similar 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 indicate readOnlyHint=true. The description adds value by stating it is deterministic and incurs no LLM cost, 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 only two sentences, front-loaded with the main action, 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 zero parameters and an output schema (present but not detailed), the description covers purpose and usage adequately. It mentions return fields (tool count, endpoint list, etc.) briefly.

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

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

There are zero parameters, so the description does not need to add parameter info. A baseline of 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, specifying the resource and action. It distinguishes itself from sibling tools by being a meta-capability 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 context. It lacks explicit when-not-to-use guidance, but the unique purpose makes it sufficient.

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