Colour Memory

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

Annotations already indicate readOnlyHint=true, and the description adds that the tool returns contrast ratios and pass/fail grades. It does not contradict annotations and provides useful behavioral context beyond the read-only status.

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

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

The description is a single, concise sentence. It front-loads the key verb and resource, with no extraneous information or redundancy.

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

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

Given the existence of an output schema and annotations, the description sufficiently explains what the tool does and returns. It is complete enough for an agent to understand the tool's role, though it omits details like the default background value (covered by schema).

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

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

Schema coverage is 100%, so the description adds limited value beyond the schema. It mentions 'foreground hex' and 'background' which map to parameters, but no additional syntax or format details 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 returns WCAG 2.1 contrast ratios and AA/AAA pass/fail grades for a foreground hex against a background. It specifies the exact resource and action, and the purpose is distinct from siblings like accessibility_font or accessibility_matrix.

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

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

The description provides no explicit guidance on when to use this tool versus other accessibility tools. The context is implied for contrast checking, but no alternatives or exclusions are mentioned among many sibling tools.

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

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

Annotations already declare readOnlyHint=true, so no destructive behavior. The description adds that it returns ranked results with grades and recommendations, but does not disclose additional traits like input validation or performance. With annotations covering safety, a score of 3 is appropriate.

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

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

A single, well-structured sentence that front-loads the key information. Every part is necessary 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 the simple tool with two parameters and an output schema (present), the description covers the core functionality completely: input conditions, ranking by contrast, WCAG grades, and specific recommendations. 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 both parameters ('background', 'palette') are already described. The description reiterates the schema but adds no new semantic value beyond what the schema provides. Baseline score of 3.

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

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

Description clearly states the tool ranks candidate foreground colors by contrast ratio with WCAG grades and provides recommendations for body text, large text, and UI components. It is specific and distinguishes itself from sibling tools like accessibility_check.

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

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

The description implies usage when needing WCAG-ranked foreground colors, but does not explicitly state when not to use it or mention alternatives among the many sibling tools. Guidance is implied rather than explicit.

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

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

Describes the return value (contrast ratios, AA/AAA grades, summary) and aligns with readOnlyHint, adding detail 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 efficient sentences: first explains core function, second provides usage guidance; no redundancy.

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

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

Given complete schema coverage, output schema, and readOnly annotation, the description fully covers input, output, and usage 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 covers 100% of parameters; description repeats the hex array format with an example but adds negligible semantic 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?

Explicitly states it accepts a palette and returns contrast combinations with grades, distinguishing from sibling 'accessibility_check' by recommending this tool for bulk evaluation.

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?

Directly advises to use this instead of calling accessibility_check multiple times for a palette, providing clear context without explicit exclusion of other cases.

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

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

Annotations already mark readOnlyHint true, and the description adds deterministic behavior and no LLM cost, which is valuable for cost and consistency expectations. No contradictions.

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

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

Two concise sentences: first captures purpose and outputs, second adds deterministic and cost properties. Every sentence adds value with zero 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 takes one parameter and outputs structured rules, the description covers all necessary behavioral information. The existence of an output schema complements the description, 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 coverage is 100% and the parameter is well-described in the schema as 'Array of hex values'. The description adds no further semantics beyond referring to 'palette', which is already implied.

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 converts a palette WCAG matrix into actionable design-system rules, listing specific outputs like safe pairs and component usage rules. This distinctively separates it from siblings like accessibility_matrix and accessibility_check.

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

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

The description implies usage when a palette is available and design-system rules are needed. While it doesn't explicitly name alternatives, the context is clear and the list of outputs guides appropriate use.

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

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

Annotations already declare readOnlyHint=true, so the description builds on this by naming the specific simulation model (Brettel-Vienot-Mollon), which adds behavioral context beyond the safety guarantee. It does not disclose potential limitations or edge cases, but the model specification is a meaningful addition.

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

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

The description is a single, well-structured sentence that front-loads the action ('Return simulated hex values') and concisely specifies the three color blindness types and the model used. 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 tool's simplicity (one parameter, output schema present), the description adequately covers the core functionality. It could mention input validation (e.g., valid hex format) or output structure, but the output schema likely handles that. Minor gap: no mention of whether the simulation is perceptual or linear.

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 the parameter 'hex_val' already documented as 'Hex value e.g. '#BE0032''. The description simply reiterates 'hex values' without adding extra meaning, format constraints, or validation rules 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 it returns simulated hex values for three specific color blindness types (protanopia, deuteranopia, tritanopia) using the Brettel-Vienot-Mollon model. This uniquely defines the tool's purpose and distinguishes it from sibling tools like accessibility_check, which likely deals with contrast checking.

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 color blindness simulation but does not explicitly state when to use this tool versus alternatives like accessibility_matrix or accessibility_rules. There is no mention of when not to use it or any comparison to 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 aligns by describing a read operation (fetching archive palette) and generating outputs without persistent changes. The description adds behavioral detail about what is fetched and produced, but does not contradict annotations.

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

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

The description is a single well-structured paragraph with front-loaded purpose and an example. It is concise without omitting key details, though a slightly more structured format could improve readability.

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

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

Given 8 parameters with 100% schema coverage and an existing output schema, the description provides a complete overview: workflow, outputs, supported models, and an example. It addresses the tool's role in the broader system 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%, so baseline is 3. The description adds minimal extra meaning beyond schema descriptions, which are already detailed. The example briefly demonstrates task, concept, and model parameters.

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 outputs and supported models, distinguishing it from sibling tools focused on analysis, audits, or branding.

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 example usage and states 'Use this to make Colour Memory the colour layer for other AI systems,' giving clear context. However, it lacks explicit guidance on when not to use this tool versus alternatives like palette_generate.

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

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

The description discloses what the tool returns (fidelity score, dE2000 distance, match quality per colour, overall verdict), adding value beyond the readOnlyHint annotation. It does not contradict the annotation. No additional behavioral traits (e.g., rate limits) are mentioned, but the read-only nature is clear.

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, efficiently conveying purpose, usage context, and output. It is front-loaded with the main action and provides necessary details 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, the description does not need to detail return values. It covers the workflow (after agent_brief + image generation), prerequisites (target palette from agent_brief), and the verification outcome. It is complete for the tool's role.

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%. The description adds workflow context by explaining that the image URL or base64 and target palette from agent_brief are needed. This goes beyond the schema descriptions, linking parameters to the overall process.

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: verifying that AI-generated images used specified colours from an agent_brief call. It uses a specific verb ('Verify') and identifies the resource ('AI Image Generation Colour Fidelity'). The context of 'agent_brief' distinguishes it from sibling colour tools.

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

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

The description explicitly advises when to use the tool: 'Use after agent_brief + image generation to close the colour loop.' This provides clear usage context. However, it does not mention when not to use it or list alternatives, though the sibling list includes many colour tools.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'No Claude call — pure archive data analysis.' It also details the outputs (health score, grade, issue counts, fix list), adding behavioral transparency beyond the annotation.

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

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

The description is two sentences, front-loaded with the core purpose and outputs, followed by usage guidance and a note on no external calls. Every sentence adds value with no redundancy.

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

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

Given the presence of an output schema, the description still covers key outputs and use cases. It addresses potential confusion by stating 'No Claude call,' and provides sufficient context for an agent to select this tool among many siblings.

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 the 'archive' parameter described as 'Archive name to audit e.g. 'British', 'Tingry', 'Byzantine'.' The description repeats 'any named archive' but adds no new semantic information 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 specifies the verb 'Run a data quality audit' and the resource 'any named archive'. It distinguishes from sibling tools like archive_search and archive_status by detailing the specific outputs (health score, grade, issue counts) that are unique to this audit function.

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 provides two concrete use cases: 'Use before building new archive content to establish a baseline, or after a batch import to verify data quality.' It does not contrast with alternatives but gives clear context for when it 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 describes a read-only operation: it finds an archive colour and generates content. The description does not contradict annotations. It adds detail about the generation process (archive finds contradiction, Claude writes content), providing insight 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: four sentences plus an example. It is front-loaded with the main action, and every sentence adds value. The example effectively illustrates usage without unnecessary detail.

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

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

The description explains the outputs (one-liner, short story, tweet) and mentions the archive search. Since an output schema exists, the description does not need to detail the exact return structure. The tool is well-contextualized for its creative purpose, though it might mention if it can handle multiple concepts or expected colours for batch use.

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

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

All three parameters are described in the schema with 100% coverage. The description adds context by explaining the role of 'concept' and 'expected_colour' in the subversion process, and provides an example that illustrates how they are used. This enhances understanding beyond the 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?

The description clearly states the tool's purpose: 'Find the most surprising archive colour for a concept and generate a memorable one-liner subverting the obvious expectation.' It specifies the inputs (concept, optional expected colour) and outputs (one-liner, short story, tweet), distinguishing it from sibling tools like archive_search which are for different tasks.

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

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

The description provides explicit examples of use ('love', 'grief', etc.) and states the intended application: 'Use this for public-facing demos, content, and brand storytelling.' It does not explicitly mention when not to use it, but the context is clear. It offers a concrete example, which helps guide the 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 declare readOnlyHint=true, and the description reinforces this by describing the tool as reporting and returning a matrix, not modifying anything. It adds behavioral context: returns coverage grades, best match, and needed source types.

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 well-structured sentences that front-load purpose and usage. Every sentence adds necessary information; 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 annotated readOnlyHint, full schema coverage, and output schema, the description is complete. It explains the tool's role in the workflow and what it returns, 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 has 100% description coverage with clear descriptions. Description adds value with concrete examples for both parameters (e.g., 'opium', 'gin', 'EIC', 'Dickens'), enhancing understanding beyond the schema.

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

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

Description clearly states the tool's purpose: given themes, report which are well-evidenced or under-evidenced. It uses specific verbs ('report', 'returns') and resource ('coverage matrix'), distinguishing it from siblings like archive_evidence_gap and archive_report_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?

Explicit usage guidance: 'Use this BEFORE building an archive_report_brief or brief_forensic' and 'Prevents building beautiful reports that quietly ignore half the brief.' Clearly indicates when and why to use this tool over alternatives.

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

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

The description fully discloses behavior beyond annotations: it details the detection logic, output fields (anachronism_risk, period_relevance, safe/unsafe phrasing), and provides a rationale. Annotations already indicate read-only, and the description aligns and adds significant context.

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

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

The description is two sentences, front-loaded with the primary action. Every sentence adds value: the first defines the core function, the second provides detailed output and a motivating example. No wasted words.

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

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

Despite no formal output schema, the description enumerates all output fields (risk levels, score, phrasing variants). Combined with clear input parameters and a real-world example, the tool is fully specified for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameters and entry fields. The description adds meaning by explaining how these parameters are used (checking entries against period boundaries and target_period) and what the outputs represent, enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool checks anachronism risk for colour entries, with specific actions (detecting date mismatches and known modern sources) and outputs (risk levels, period_relevance score, safe/unsafe phrasing). The example reinforces its purpose, distinguishing it from sibling tools.

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

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

It explicitly says 'Essential for historical documents' and provides a concrete scenario, indicating when to use. It does not list alternatives or when not to use, but the context is sufficiently clear given the tool's unique function among siblings.

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

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

Annotations already mark the tool as readOnlyHint=true. The description adds that it returns support levels and safe wording, but does not elaborate on other behavioral aspects like rate limits or error handling. The description is consistent 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 a single paragraph that efficiently conveys the tool's purpose, role, and example. It is front-loaded with the core function, though a more structured format could improve readability.

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

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

With an output schema present and moderate complexity, the description covers core inputs, output types, and use cases. It lacks discussion of edge cases or error conditions but is sufficient for standard 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 description coverage is 100%, so the schema already documents each parameter. The description adds an example that illustrates usage but does not provide new semantic insights beyond what is in the schema.

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

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

The description clearly states that the tool takes a hex value and a proposed claim, and returns archive support, missing elements, needed source type, and safe wording. It positions itself as an anti-hallucination endpoint, distinguishing it from sibling tools like archive_search or archive_cliche.

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 when to use it—to verify claims against an archive—and provides an example. However, it does not explicitly mention when not to use it or list alternative tools, though the sibling context implies its specialized role.

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) and provides rich behavioral context: it separates documented fact from inference, returns specific evidence details, and positions itself as a trust endpoint. 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 well-structured sentences: purpose, return fields, and strategic value. Every sentence adds essential information 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 simple parameter set and presence of output schema, the description fully covers what the tool does, why it matters, and what it returns. 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 is 3. The description provides examples of colour names but adds no new semantic meaning beyond the schema for the single parameter.

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

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

The description clearly states the tool explains provenance of named archive colours with explicit separation of fact, derivation, and interpretation. It is distinct from sibling colour tools which focus on other aspects like story, harmonies, 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 identifies this as the trust endpoint for provenance queries and states it is essential for intellectual honesty. It implies when to use it but does not explicitly contrast with siblings or state 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?

The description provides extensive behavioral details: 'Two Claude calls total,' and a full breakdown of output components (ranked colour cards, provenance, story order, source confidence flags, etc.). The annotations have readOnlyHint=true; the description describes a read-oriented research operation, consistent with readOnly. No contradiction. The description adds significant context beyond annotations.

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

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

The description is three sentences, each efficiently adding essential information: purpose and scope, input/output summary, replacement info, and usage directive. It front-loads the core value proposition. No unnecessary words; every sentence earns its place.

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

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

Given the tool's complexity (7 params, rich inputs/outputs), the description covers purpose, inputs, outputs, replacement for chaining, and usage order. An output schema exists, so the description appropriately does not reiterate return structure. It is complete for an agent to understand when and how to use the tool.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters with descriptions. The tool description adds some context (e.g., 'themes' are 'Research themes'), but it largely repeats or slightly extends schema content. Per guidelines, with high coverage (>80%), baseline is 3, and the description does not provide significant additional 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?

The description begins with 'One-call complete archive research package for a document, PDF, or editorial brief,' clearly stating the action and resource. It lists specific inputs and outputs. It explicitly distinguishes from sibling tools by noting it replaces chaining 'archive_search + get_colour_card + cliche_breaker + agent_brief separately.' This is a specific verb+resource that differentiates from 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 includes 'Use this first for any document workflow,' giving clear when-to-use guidance. It also states what it replaces, implying alternatives. However, it does not explicitly state when not to use this tool or mention specific exclusions. Still, the context is clear and helpful.

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

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

Annotations declare readOnlyHint=true, which description aligns with (search operation). Adds context about search scope (all archive colour names and notes) and types of matches (name fragment, material, cultural reference, pigment type, historical period). No contradictions.

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

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

Two concise sentences with key info front-loaded: first sentence states core function, second adds examples and distinguishes from sibling. No wasted words.

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

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

With output schema present and schema covering all parameters, description provides sufficient context for a search tool. Mentions return behavior differences for include_full, but schema already 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 coverage is 100% with detailed parameter descriptions. The description does not add significant per-parameter meaning beyond schema. Baseline 3 appropriate as schema already covers semantics.

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

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

Clearly states 'Full-text keyword search across all archive colour names and notes' and provides specific search examples (cerulean, Prussian, Ottoman). Distinguishes itself from sibling tool query_conceptual by complementing conceptual embedding search with exact keyword matching.

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

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

Explicitly mentions complementing conceptual embedding search, implying when to use this tool (exact keyword matching) vs alternative (query_conceptual). Provides examples of search types but does not explicitly state when not to use.

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

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

Annotation already declares readOnlyHint=true, so description adds limited value. Does not mention any additional behavioral traits like latency, authentication, or side effects.

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

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

Single sentence with no wasted words, front-loads the verb and resource, efficiently conveys the output contents.

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 returns a status object, the description enumerates key fields, which is sufficient. Output schema exists, so further detail is not required.

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

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

No parameters exist, and schema coverage is 100% given empty schema. Description appropriately lists what the tool returns, so baseline 4 is justified.

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

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

The description clearly specifies the verb 'Return' and the resource 'archive status', listing specific data items (color count, breakdown, model, etc.), which distinguishes it from sibling tools like archive_search.

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

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

No guidance on when to use this tool versus alternatives. Lacks context about when-not-to-use or prerequisites for calling the tool.

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

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

The description states 'Deterministic. No LLM cost,' which adds meaningful behavioral context beyond the readOnlyHint annotation, confirming safe, cost-free reuse. 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?

Three sentences, each dense with information: purpose, output list, behavioral traits. No wasted words, front-loaded with the key action 'Returns'.

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

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

Given the existence of an output schema, the description sufficiently covers the tool's purpose and outputs. It could optionally note the required palette parameter, but overall it is complete for an agent to understand what this tool delivers.

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

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

With 100% schema description coverage, the schema already documents each parameter. The description adds high-level context for the output but does not enhance parameter meaning significantly; baseline 3 is appropriate.

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

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

The description uses a specific verb 'Returns' and lists concrete resources (CSS variables, Tailwind config, Figma tokens, etc.), clearly distinguishing it from sibling tools like brand_audit or brand_report that focus on analysis rather than generation.

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

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

The phrase 'Everything a brand team needs to ship' implies a comprehensive use case, but there is no explicit guidance on when to prefer this tool over siblings, nor any exclusions or alternatives 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?

Discloses that all data is computed with 'no LLM cost', adding context beyond 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?

Well-structured and front-loaded with purpose. Slightly verbose with detail on outputs but every sentence is 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 output schema exists, description adequately covers return values. All 5 parameters are explained or mentioned. No gaps for a tool of this complexity.

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

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

Schema coverage is 100%, but description adds value by listing parameters and providing context (e.g., 'digital | print | both' for medium). High baseline but description still helpful.

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 the comprehensive outputs. It distinguishes itself by replacing chaining of multiple separate tools, making the purpose unambiguous.

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

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

Explicitly states when to use this tool ('Replaces chaining...') and provides guidance on next steps ('Pass results to an LLM for written narrative'). No ambiguity about alternatives.

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

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

Annotations already declare readOnlyHint=true. The description adds behavioral details: returns CIEDE2000 distance, distinctiveness score, ownership verdict, and strategic recommendation. It discloses that it is a read-only analysis, consistent 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 well-structured sentences: first a purpose-question, second a bullet-like listing of inputs/outputs and usage. Every word earns its place; no fluff.

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

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

Given the tool's complexity (6 parameters, output schema present, read-only annotation), the description covers purpose, usage, and key outputs. It does not detail calculation methodology, but that is acceptable for an agent's decision to invoke.

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

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

Schema coverage is 100%, so all parameters have descriptions in the schema. The description reiterates the input list but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a clear question ('Can this brand own this colour...') that defines the tool's purpose. It lists specific inputs and outputs. It distinguishes from similar tools like colour_compare 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?

Explicitly states 'Use before committing to a brand colour in a competitive market.' This gives clear when-to-use context. It does not provide explicit when-not-to-use or compare with sibling tools, but the usage scenario is well-defined.

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

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

Annotations already declare readOnlyHint=true. The description adds valuable behavioral context: the tool runs entirely internally with no chained calls and cannot be blocked by agent safety filters. However, the mention of 'Two Claude calls total' introduces minor ambiguity about internal execution.

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

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

The description is concise and front-loaded with the key purpose. It uses a single paragraph that efficiently conveys inputs, outputs, and alternatives. Slight improvement could be made with bullet points for clarity.

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

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

Given the tool's complexity (7 parameters, nested objects, output schema), the description covers purpose, inputs, outputs, usage context, and behavioral constraints. The output schema exists, so return values need not be detailed. The description fully contextualizes the tool within its sibling group.

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 lists input parameters but does not add meaning beyond what the schema already provides for each parameter.

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

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

The description clearly states the tool's purpose as a one-call complete brand colour intelligence report. It lists inputs and outputs and explicitly distinguishes itself from sibling tools by recommending using this tool instead of chaining colour_strategy, cliche_breaker, ecommerce_product_copy, memory_hooks, 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: as a consolidated alternative to chaining multiple related tools. It also lists required inputs, making it clear what the agent needs to provide.

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 annotations (readOnlyHint=true), the description explicitly states 'Deterministic. No LLM cost.' This provides valuable behavioral context not captured in structured fields, ensuring the agent knows the tool is deterministic and free of LLM usage.

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: one sentence summarizing purpose, followed by a list of outputs, and then behavioral traits. Front-loaded with the key value proposition. Every sentence earns its place 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 has 5 parameters (1 required) and an output schema, the description fully covers what the tool does, its behavioral properties, and its output. The output schema likely structures return values, so the description need not repeat them. Complete for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaningful detail about parameters beyond what the schema provides (e.g., no explanation of how 'market' or 'medium' affect output). No additional semantic value.

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

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

The description clearly states the tool provides a complete brand colour system in one call, listing specific outputs (colour roles, light/dark maps, typography, usage rules, design tokens, citation cards). It clearly distinguishes from siblings like colour_card or palette_* by emphasizing comprehensiveness.

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 this is a one-stop shop for brand colour systems, but does not explicitly state when to use alternatives. Siblings like colour_card or palette_* suggest narrower use cases, but the description lacks explicit 'when not to use' or alternative recommendations.

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

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

Annotations already mark readOnlyHint=true. Description adds context about what data is returned, which is consistent. However, no additional behavioral traits (e.g., performance, pagination, or limitations) are disclosed 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?

One sentence, 15 words, no filler. Information is front-loaded. 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?

Given the presence of output schema (not shown but indicated), annotations, and full schema coverage, the description is complete. It clearly states purpose and return data, and no critical details are missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds examples but no extra semantic value. With full schema coverage, baseline 3 is appropriate.

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

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

Description clearly states the tool looks up a named colour and returns specific data (hex, archive, provenance, cultural notes). The title also clarifies it's by name. However, it does not explicitly distinguish this 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?

No guidance on when to use this tool versus alternatives. No mention of when not to use it or prerequisites. The agent is left to infer usage from purpose alone.

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

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

Annotations already declare readOnlyHint=true. The description adds behavioral context by listing return fields and the condition on number of colours. No contradiction, and the description complements 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?

Two concise sentences front-loaded with the action verb 'Assess', followed by specific outputs and context. No redundant information.

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

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

Given low parameter count (2), full schema coverage, and presence of output schema, the description adequately covers all necessary context. It specifies constraints (2-5 colours, context) and expected returns.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the output (harmony, clash, etc.) and the contextual usage, going beyond mere parameter listing.

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 2-5 colours for a specific context and lists concrete outputs (harmony type, clash warnings, contrast summary, deployment rules). It distinguishes from sibling tools by specifying the combination assessment and output 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?

The description implies use when assessing colour combinations for a context but does not explicitly guide when to use this tool over siblings like colour_harmonies or palette_verdict. No exclusion criteria or alternatives are mentioned.

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

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

Annotations already provide readOnlyHint=true. Description adds that it returns quantified differences and cultural context, which is consistent. No additional side effects or constraints mentioned, but sufficient given the non-destructive nature.

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

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

Description is concise (3 sentences) and well-structured. Front-loaded with main function, followed by use case and exclusion. No redundant 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 only 2 simple parameters, 100% schema coverage, and an output schema (not shown but existence noted), the description is complete enough. It covers purpose, usage, and output nature without needing more detail.

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 and example values for both hex parameters. Description does not add further meaning beyond the schema context, so baseline score of 3 is appropriate.

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

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

Description clearly states the tool compares two hex values, returning quantified differences (LRV, chroma, hue angle, warmth, CIEDE2000) and cultural context. It specifies that it is a decision/reasoning tool, not a harmony tool, distinguishing it from siblings like colour_harmonies.

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

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

Explicitly describes when to use: when choosing between two colours or explaining why one works better. Also explicitly excludes harmony use cases with 'Not a harmony tool — this is a decision and reasoning tool.'

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

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

The annotation declares readOnlyHint=true, and the description confirms it returns warnings, positive associations, and market flags—matching the read-only behavior. It adds context about the output format without contradicting annotations.

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

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

Three sentences cover purpose, usage, and data source without redundancy. Front-loaded with the core action and quickly specifies input types.

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 straightforward inputs (3 optional params), the description sufficiently explains what the tool does, when to use it, and what it returns. No gaps for the complexity level.

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

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

All three parameters (hex, markets, palette) have descriptions in the schema, achieving 100% coverage. The description adds minimal additional insight beyond schema, e.g., mentioning 'specific market flags'. 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 assesses cultural sensitivity for hex values or palettes, with a specific goal of global brand deployment. It distinguishes from siblings like colour_verdict or palette_verdict by focusing on cultural risk rather than general colour assessment or generation.

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

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

The description explicitly advises use before global brand deployment, providing clear context. It does not name alternatives or exclusions, but the purpose is distinct enough among siblings to imply when to use.

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

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

The description discloses important behavioral traits beyond the readOnlyHint annotation: 'No Claude call -- pure archive and physics data. Fast and cacheable.' This informs the agent that the tool is lightweight, deterministic, and safe (no external calls), which is valuable for decision-making.

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 opens with the core purpose, lists key output fields, then provides technical context and usage guidance. Every sentence adds value, and there is no unnecessary information.

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

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

For a tool with a single required parameter and no nested objects, the description is complete. It explains what the tool does, what inputs it takes, what outputs it produces, and when to use it. The presence of an output schema (mentioned in context) further supports completeness.

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

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

The input schema covers the single parameter 'hex' completely with a description and example. The description does not add additional meaning beyond what the schema provides, but it does list the output fields, which indirectly contextualizes the parameter. Given 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a 'Compact semantic fingerprint for any hex colour' and lists the specific attributes returned (depth, temperature, chroma band, etc.). It distinguishes itself from sibling tools by emphasizing 'No Claude call -- pure archive and physics data' and being fast and cacheable, which is unique among the many colour-related tools.

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

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

The description provides explicit guidance on when to use the tool: 'Use when an agent needs to reason about a colour semantically without reading long prose. Ideal for filtering, ranking, or comparing colours.' It does not explicitly mention when not to use it or list alternatives, but the context is clear and helpful 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?

Description details return fields (verdict, risks, actions, light behaviour, substrate notes, alternative) and confirms read-only operation, consistent with 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?

Description is a single paragraph that front-loads the purpose. It is concise but could be structured more cleanly (e.g., bullet points for output items) 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 5 parameters and an output schema (not shown but described), the description fully covers input context, output structure, and backing methodologies (CIEDE2000, Claude knowledge). No gaps.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value through examples but does not provide additional parameter-level meaning beyond what the schema already offers.

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

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

Description clearly states the tool assesses hex colour safety for physical applications, with a specific verb and resource. It distinguishes from siblings like colour_compare or colour_verdict by focusing on physical substrate safety.

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

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

Description provides explicit use contexts via examples (ultramarine on lime plaster, etc.), helping the agent understand when to invoke. However, it does not explicitly mention when not to use or name alternative tools.

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

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

The annotations already provide readOnlyHint=true, and the description confirms a read operation ('Return'). However, it does not disclose additional behavioral traits such as what happens if the hex does not match an archive colour or any performance implications. The description adds only the 'named archive colours' context, which is valuable but limited.

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 is front-loaded and every word serves a purpose. It is highly concise with no redundant information.

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

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

Given that an output schema exists and annotations are present, the description is minimally adequate. However, it does not clarify how 'named archive colours' relate to the hex input or what constitutes a match, leaving a gap for complex scenarios.

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

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

Schema coverage is 100% with clear descriptions for both parameters (hex and harmony_types). The description does not add significant meaning beyond the schema, only noting that harmonies are 'matched to named archive colours', which slightly enriches the context but does not deeply explain parameter usage.

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

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

The description uses a specific verb 'Return' and clearly lists the resources (complementary, triadic, analogous, split-complementary harmonies) and target ('named archive colours'), effectively distinguishing it from sibling tools like colour_combination or colour_compare.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It only implies use through the tool name and mention of 'archive colours' but lacks clear context for 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 indicate readOnlyHint=true. The description adds behavioral context: it is backed by archive colour provenance and tunable by audience and tone. No destructive behavior is hinted. This goes beyond the annotation, providing useful trait 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?

Two sentences pack a wealth of information: outputs, backing data, tunability, and use cases. Every word is purposeful, front-loaded with the core action. No redundancy.

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

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

Given the output schema exists (not shown but referenced), the description adequately covers what the tool produces and how it can be tuned. It is complete for an agent to understand the tool's role and when to use it, though it could mention the return format or output schema 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?

All three parameters are fully described in the schema (100% coverage). The description reinforces the role of hex, tone, and audience by emphasizing tunability. While not adding new syntax details, it provides context that enhances understanding of parameter usage.

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

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

The description clearly states the tool generates a hook sentence, story, tweet, image prompt, and follow-up questions for a hex colour. This specific verb+resource combination, along with the mention of cultural provenance and tunability, distinguishes it from colour-related siblings like colour_story or colour_namer.

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 cases: 'make archive colours shareable, to generate content, or to power a public-facing colour chat experience.' It does not specify when not to use or contrast with alternatives, but the given context is sufficient for an agent to decide when to invoke 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 include readOnlyHint=true, confirming safe read operation. The description adds no extra behavioral context beyond 'find', which is consistent. No additional traits disclosed.

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, 14 words, clear and front-loaded. No superfluous 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?

With output schema present and 3 well-documented parameters, the description provides sufficient context for this simple lookup tool. Could mention return format, but output schema likely covers it.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions brands in text, but the parameter description already does that. No additional 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?

Clearly states the tool finds the nearest named colour in commercial paint systems, specifically naming Farrow and Ball and Little Greene. This distinguishes it from sibling colour tools like colour_compare or colour_namer.

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 hex value needs to be matched to a named colour from specified brands. However, it does not explicitly state when not to use it or mention alternative sibling tools.

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

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

Annotations already set readOnlyHint=true, so the description's mention of 'Return' aligns. It adds value by listing specific metrics and illuminant conditions, but does not disclose other behavioral traits like rate limits or output size. With annotations covering safety, a score of 3 is appropriate.

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

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

Single sentence, no unnecessary words, front-loaded with the action and key details. 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?

For a simple, one-parameter tool with output schema, the description covers the essential metrics and illuminants. However, it omits any usage context or prerequisites; a slightly richer context would push it to 5.

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

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

Schema coverage is 100% with a clear description for hex_val. The description adds context about the computed metrics but does not add meaning beyond the schema for the parameter itself. Baseline 3 is correct.

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

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

The description explicitly states the tool returns perceptual colour metrics (LRV, chroma, hue angle, warmth, illuminant shifts) from a hex value, clearly differentiating it from sibling tools like colour_compare or colour_dna which have different purposes.

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

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

No guidance is provided on when to use this tool vs alternatives like colour_compare or colour_harmonies. The description lacks context such as prerequisites or exclusions, leaving the agent to infer usage purely from the name.

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 read-only operation (consistent with readOnlyHint=true), explains the perceptual model (CIE Lab subtractive), and specifies outputs (mixed hex, nearest archive match with cultural context). 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?

Concise three sentences: purpose, model, and concrete example. No wasted words; front-loaded with key information. Structure supports 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?

Given output schema exists (not shown but signaled), description adequately explains return values. Covers purpose, parameters, model, and example output. No obvious gaps for an agent to incorrectly invoke the tool.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds conceptual meaning (subtractive model, ratio range, example) beyond schema definitions, enhancing understanding for the agent.

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 simulates perceptually modelled subtractive mixing of two colours in CIE Lab space, distinguishing it from RGB blending. Verb 'mix' and resource 'two colours' are specific. Differentiates from sibling colour tools by specifying the perceptual model and example 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?

Provides clear context for when to use (mixing two specific colours for perceptual accuracy) with an example. Does not explicitly state when not to use or name alternative sibling tools, but the purpose is sufficiently scoped.

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 correctly implies a read operation ('generate'). It adds context about archive verification and style selection. However, it does not address error cases (e.g., hex not found in archive) or rate limits.

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

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

Four sentences, no fluff. Front-loaded with the core purpose, then details on styles and use case. Every sentence contributes essential 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 (not shown) and complete parameter descriptions, the description provides sufficient context. It identifies the key use case and style constraints, though it could briefly mention what 'archive-verified' entails.

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

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

Schema description coverage is 100%, but the description adds value by listing the style options (geographical, poetic, etc.) and mentioning archive grounding, which clarifies the context. Still, most parameter meaning is already in the schema.

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

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

The description clearly states the tool's purpose: generate archive-verified colour names for any hex value, with multiple naming styles. It distinguishes from siblings by specifying unique features (archive grounding, Shopify product 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 implies usage for colour naming (e.g., 'core of Shopify product naming') but does not explicitly state when to use this tool versus siblings like colour_slugs or ecommerce_namer. No when-not-to or alternative 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 indicate readOnlyHint=true, and the description is consistent with that read-only behavior. It adds context about how names are sourced ('Archive-grounded' with dE2000 distance), which is useful behavioral info beyond the annotation. No contradictions.

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

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

Two concise sentences with no redundancy. Each sentence provides distinct information: first lists output formats, second adds source context. Front-loaded with core purpose.

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

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

Output schema exists, so return values need not be described. The description covers what the tool does and the name generation context. It could be more explicit about the output structure (e.g., 'returns an object with keys for each format'), but given the output schema, the current description is adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema; it only reiterates the hex input and mentions 'archive filter' implicitly. It does not provide format constraints or elaboration on the archive parameter.

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

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

Description clearly states the tool returns developer token formats for a hex value and lists specific formats (CSS variable, kebab-case, etc.). It mentions 'Archive-grounded name source' but does not explicitly distinguish from siblings like colour_namer or colour_hooks, though the specific token focus provides some 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?

No explicit guidance on when to use this tool versus alternatives. The description does not state use cases, prerequisites, or when not to use it. With many sibling colour tools, this omission leaves the agent without decision support.

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 does not need to state that. It adds behavioral context by describing the returned narrative's contents (history, meanings, archive names). This is standard for a read-only retrieval tool.

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

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

The description is three well-structured sentences, front-loaded with the core functionality, followed by use cases and an illustrative example. No unnecessary words; every sentence serves a purpose.

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

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

Given the presence of an output schema and annotations, the description covers the tool's purpose, use cases, and provides an example. It could mention expected behavior for invalid inputs, but overall it is sufficiently complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description only mentions the hex parameter implicitly ('Given a hex value') and provides an example. It does not add new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: given a hex value, it returns a rich narrative about the colour's cultural journey, including historical appearances, meanings across civilizations, and archive names. This distinctively places it among many colour siblings by focusing on cultural/historical narrative.

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

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

The description says it is 'essential for image generation prompts, brand storytelling, and creative briefs,' providing clear context for when to use. However, it does not explicitly exclude alternatives or mention when not to use it, missing the full when-to-use/when-not-to guidance.

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

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

Annotations declare readOnlyHint=true, so the tool is safe for reads. The description adds that it 'combines archive grounding' etc., but does not elaborate on behavioural impacts like dependencies on other tools or potential performance. Without annotations, this would be insufficient, but with them it meets the minimum.

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?

Every sentence adds value: purpose, inputs, outputs, and examples. The structure front-loads the key information and avoids fluff. Despite length, it 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 (5 parameters including nested objects, rich outputs listed, and an output schema present), the description covers all critical aspects: what it does, inputs, outputs, and usage examples. No gaps remain.

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

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

Schema coverage is 100%, and the description reinforces the parameter structure ('Input: hex + brand_context ...') in a more readable format, adding grouping context. This goes beyond the schema by explaining how parameters relate to the overall strategy.

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 'flagship commercial endpoint' that combines multiple specialised checks (archive, verdict, brand fit, etc.), distinguishing itself from sibling tools that handle specific aspects. The verb 'combines' with explicit outputs and examples makes 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 this is the comprehensive tool for a full colour strategy, and the sibling list suggests alternatives for isolated checks. However, it does not explicitly state when to avoid this tool or prefer a sibling, which would enhance guidance.

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

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

The description adds behavioral context beyond the readOnlyHint annotation: it specifies that the tool returns appearances in chronological order, from earliest to modern associations. This provides a clear mental model of the tool's operation.

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

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

The description is very concise: two sentences plus an example. The main action is front-loaded, and every sentence adds value. The example effectively illustrates the tool's function.

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

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

Given that the tool has an output schema and 100% schema coverage, the description need not explain return values. It sufficiently covers the tool's purpose, usage suggestion, and behavioral details, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the schema already fully defines the parameters. The description does not add new semantic details about the parameters beyond repeating 'hex value'; tolerance is not mentioned. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: traces a colour's appearances across cultures and centuries in chronological order. It uses specific verbs ('traces', 'shows') and distinguishes itself from sibling tools like colour_story or colour_forensics by focusing on chronological history.

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

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

The description indicates the tool is 'essential for understanding why a colour carries the weight it does,' which implies its use for historical context. While not explicit about when not to use, this guidance is clear enough for an AI agent to infer appropriate contexts.

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

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

Annotations already mark readOnlyHint=true, so the description's 'return' aligns. No additional behavioral traits (e.g., authentication needs, rate limits) are disclosed. The description adds no new behavioral context 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?

Two sentences, no filler. The first sentence lists outputs, the second provides context. Every word is meaningful and front-loaded.

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

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

For a simple tool with one parameter, annotations, and an output schema, the description is sufficient. It explains the purpose, outputs, and target user. Missing a brief note on response structure, but output schema covers that.

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

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

Schema coverage is 100% with a description for the 'name' parameter. The description repeats 'named archive colour' but adds no extra semantics like format, examples (beyond schema's example), or validation rules. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns historical variants, lighter/darker versions with archive matches, and cultural siblings. The verb 'return' is specific and the resource is well-defined. The sibling tools (e.g., colour_dna, colour_forensics) are distinct, so this purpose stands out.

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

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

The description says 'Essential for designers exploring around a colour' which gives a use case but no explicit when-not-to-use or alternatives. Among many sibling tools, the description could better guide when to use this versus colour_dna or colour_timeline.

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 declare readOnlyHint=true, and the description adds value by stating the tool is 'Backed by CIEDE2000 archive matching and Claude cultural intelligence' and outlines output contents (strengths, risks, etc.). 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 at two sentences plus examples, with no wasted words. It front-loads the core purpose and then elaborates with output details and illustrative 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?

Given the tool's complexity (5 parameters, 100% schema coverage, and an output schema), the description covers the purpose, output structure, underlying methods, and example use cases. It is sufficiently 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% documentation coverage, so each parameter is already described. The description adds context about what the parameters are used for (e.g., 'What the colour will be used for') but does not add meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool evaluates a hex colour for a specific use case, market, and medium, and returns a decisive verdict. It includes the possible verdict values and distinguishes itself from siblings by focusing on verdict rather than other aspects like cultural risk 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 when to use the tool: when a colour verdict is needed for a given context. It provides examples of use cases but does not explicitly state when not to use or mention alternatives among sibling tools. However, the examples and clear purpose give sufficient guidance.

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

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

Annotations declare readOnlyHint: true, so the description does not need to re-state safety. It adds that this is a compound tool aggregating multiple sub-tools, which is useful behavioral context. No side effects are disclosed beyond what annotations imply.

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 clear and front-loaded but could be slightly more concise. It effectively communicates the tool's purpose and usage guidance in a single paragraph.

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 (compound, 7 params, multiple outputs), the description covers the key input concepts and output items. The presence of an output schema reduces the burden on the description to detail return values.

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 7 parameters have schema descriptions (100% coverage), so the description adds limited new information about parameters. It mentions 'concept, medium, audience, and constraints' but 'audience' is not a parameter, which is a minor mismatch. The description does not elaborate on parameter specifics 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's a one-call compound tool that produces a complete design package from a concept, medium, audience, and constraints. It explicitly lists the outputs and distinguishes from siblings by naming the individual tools it replaces, such as query_conceptual and palette_from_concept.

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

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

The description provides explicit guidance: '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.' This states both when to use and when not to use, with clear 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 key behavioral traits: copy is grounded in archive provenance (not generic AI), colour names come from nearest archive match, and provides examples. This adds context beyond the readOnlyHint annotation, which is consistent with the tool's 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 concise and well-structured: opens with the tool's main action, details inputs and outputs, explains the unique value proposition, and closes with concrete examples. No redundant sentences.

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

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

The description is complete given the presence of an output schema. It covers purpose, all inputs, outputs, and unique value. For a tool with 5 parameters and 2 required, this is sufficient contextual information.

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

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

Schema coverage is 100% and each parameter has a description. The description adds value by summarizing the overall input-output relationship and providing examples that clarify expected formats (e.g., 'velvet cushion in Murex Luxury').

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

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

The description explicitly states the tool generates complete ecommerce product copy for any colour, listing inputs and outputs. It distinguishes from siblings like ecommerce_namer by focusing on full copy generation rather than just naming.

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

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

The description implies usage for generating product copy but does not explicitly state when to use versus alternatives like ecommerce_namer or other copy tools. No exclusion criteria or sibling comparisons are provided.

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

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

Description adds significant context beyond the readOnlyHint: it explains names are archive-sourced with defendable citations, providing transparency about the output's reliability and sourcing.

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 well-organized with main purpose first, then inputs, outputs, and use cases. Slightly verbose but remains focused and informative.

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

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

Given the tool's complexity (5 params, output schema), the description covers all aspects: use cases, inputs, output structure, and sourcing reliability, making it complete without needing output schema 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 coverage is 100% so baseline is 3; description adds value by listing inputs and detailing the output structure (archive name, citation, dE2000 distance, etc.), exceeding mere schema repetition.

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

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

The description clearly states the tool generates archive-grounded colour names for up to 40 SKUs, lists inputs and outputs, and differentiates from siblings like colour_namer by emphasizing archival sourcing and citations.

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

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

It explicitly lists suitable domains (paint, candles, fashion, etc.) but does not provide when-not-to-use or explicitly compare to alternatives, though the context makes it 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?

Adds 'image never stored, processed in memory only' beyond the readOnlyHint annotation. Also details algorithm (K-means++, Bradford chromatic adaptation) for transparency.

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 paragraph with clear sentences, no wasted words. Front-loaded with verb and purpose.

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

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

Covers input format, algorithm, return details, use cases, and privacy. Output schema exists, so no need to detail returns. Complete 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%, but description adds context on output (archive name, cultural story, RAL, WCAG) and reiterates key constraints. Adds 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 'extract its dominant colour palette' with matching to archive entries. It distinguishes from sibling tools like palette_generate and palette_compare by focusing on image upload and extraction.

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 (product photography, interior photos, etc.), but does not mention when to avoid or alternatives. Clear enough for typical usage.

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

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

The description discloses key behavioral traits beyond the readOnlyHint annotation: it uses Claude Vision and CIEDE2000 for analysis, and explicitly states that the photo is never stored. These details add significant transparency about how the tool operates.

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, providing essential information without superfluous text. It could be slightly more compact, but it efficiently conveys the tool's function, process, and example 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 complexity of the tool, the description covers all necessary aspects: what it does, what inputs are needed (a portrait photo), what outputs to expect (seasonal type, depth, undertone, palette), the method (Claude Vision, CIEDE2000), and data handling (photo never stored). The presence of an output schema compensates for not detailing return values.

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

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

Schema coverage is 100%, so all parameters are described. The description adds extra semantic value with practical tips like 'Easier than base64 for MCP use' for image_url and 'Face should be clearly visible in natural light' for image_base64, and clarifies that either image_url or image_base64 is required.

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 a personal colour analysis. It lists specific outputs (seasonal type, depth, undertone, palette) and distinguishes itself from sibling tools by focusing uniquely on personal colour analysis from a photo.

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

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

The description gives clear context on how to use the tool (upload a portrait photo) and includes an example. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions. Despite this, the uniqueness of the tool makes the usage fairly 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 annotation already declares readOnlyHint=true, so the description does not need to emphasize safety. It adds context about input and output structure (list of colour entries, return fields), but does not disclose any hidden behaviors (e.g., rate limits, authentication). This is acceptable but not exceptional.

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

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

The description is efficiently structured, opening with the core purpose and metric examples, then listing input/output format and use cases. Every sentence contributes meaningful information without redundancy.

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

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

The description covers the tool's purpose, input/output details, and typical usage scenarios. Since an output schema exists, it does not need to detail return values. The examples (e.g., 'blood as prognosis') add color, but the description is slightly brief on how the scoring basis parameter affects 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?

The schema already describes all parameters with 100% coverage. The description's mention of input fields ('name, hex, archive, source, notes') mirrors the schema, adding no new semantic value. Baseline of 3 is appropriate.

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

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

The description clearly states that the tool is a proprietary semantic metric that 'score[s] how tightly the material origin of a colour aligns with its social consequence,' with specific score examples. It differentiates from siblings by claiming this as the distinguishing metric of Colour Memory.

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 explicit use cases ('investigative reports, forensic briefs, museum content, editorial PDFs') and positions the tool as 'the metric that separates Colour Memory from palette generators.' However, it does not mention when not to use this tool or specify 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 set readOnlyHint=true, indicating no side effects. The description adds that the tool 'generates' output, which is consistent with read-only behavior (no mutations). It does not add further behavioral context (e.g., API dependencies, latency, or data sources), so it meets the baseline but does not exceed it.

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

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

The description is concise at ~100 words, with each sentence adding value. It is front-loaded with the main purpose and includes examples, output features, and a pointer to the PDF tool. No fluff or redundancy.

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

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

Given the presence of an output schema (not shown) and read-only annotations, the description provides all necessary context: it specifies inputs, outputs, and use cases. It covers the tool's full scope without needing additional explanation.

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 input schema already describes each parameter. The description adds collective context (e.g., examples of concept values) but does not provide individual parameter details beyond the schema. With high coverage, a score of 3 is appropriate per rubric.

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

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

The description clearly states the tool generates a complete interior colour specification from a concept. It specifies inputs (room concept, type, style) and outputs (colour scheme with 60/30/10 assignments, cultural provenance, paint matches, light behaviour, etc.). However, it does not explicitly differentiate from sibling tools like palette_specify or palette_generate, which may cause confusion about which tool to use for different colour tasks.

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

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

The description provides explicit usage context with examples ('bold maximalist living room', 'calm Scandi bedroom') and directs to the PDF tool for a downloadable version. It implies use when a full interior colour consultation is needed, but does not state when not to use it or compare to alternatives like palette_specify for simpler colour schemes.

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

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

Annotations indicate readOnlyHint=true, and the description adds that the tool is deterministic, incurs no LLM cost, and returns specific items (tool count, endpoint list, etc.), providing 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?

Three sentences, no wasted words, front-loaded with the core purpose. 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?

For a simple discovery tool with no parameters and an output schema, the description covers what it returns and when to use it, 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?

With zero parameters and 100% schema description coverage, the description doesn't need to add parameter info. It mentions the return values, which is beneficial. Baseline 4 is appropriate.

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

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

The description clearly states the tool returns a live inventory of all active endpoints and MCP tools, distinguishing it from sibling tools that perform specific tasks like accessibility checks or brand audits.

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

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

Explicitly advises using this tool first to discover API capabilities before making calls, and mentions it's deterministic with no LLM cost, though it doesn't specify when not to use it or list alternatives.

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

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

Beyond readOnlyHint annotation, description adds 'Deterministic, no LLM cost', specifying key behavioral traits. Also describes return value structure (score 0-100, grade, prioritised fix list). No contradictions.

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

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

Three sentences, front-loaded with core purpose, efficient with no redundant language. 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?

Complete description for a comprehensive audit tool with good annotations and output schema. Covers purpose, scope, output, and usage context. 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 parameters are already defined. Description adds no additional parameter-specific guidance but indirectly gives context via audit dimensions. 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?

Clear verb 'audit' with specific scope: 'Full palette quality audit' listing five scored dimensions (accessibility, cultural risk, tonal balance, colour diversity, archive naming strength). Distinguishes from sibling single-dimension tools like cultural_risk or accessibility_check.

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

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

Explicitly states 'use before shipping any palette' and labels it an 'Enterprise quality gate', providing clear when-to-use context. Does not explicitly list alternative tools for narrower checks, but the sibling set implies them.

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