Colour Memory

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

Annotations include readOnlyHint=true, so the safe read-only nature is already known. The description adds the scope constraint 'single foreground/background pair' but no further behavioral details like return format or edge cases. No contradiction with annotations.

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

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

The description is two sentences with no fluff, front-loading the core function and then giving a concise alternative recommendation. Every sentence earns its place.

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

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

For a simple 2-parameter read-only tool with an output schema, the description covers purpose and usage adequately. The alternative guidance adds context. It lacks mention of output specifics, but the output schema likely covers that, so no major gaps.

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

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

Schema description coverage is 100% with clear descriptions for both parameters (hex_val and background). The description adds no additional parameter-level meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states 'Evaluates contrast for a single foreground/background pair' with a specific verb and resource, clearly distinguishing it from accessibility_matrix for palettes. It answers what the tool does unambiguously.

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 provides when-to-use guidance: 'For palettes or multiple colours, use accessibility_matrix instead, it replaces multiple accessibility_check calls in one response.' This names the alternative and clarifies scope, leaving no ambiguity.

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

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

The description discloses the behavioral outcome (ranked list with WCAG grades and recommendations), which adds context beyond the readOnlyHint annotation. It does not contradict the annotations, and no side effects or prerequisites are hidden.

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

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

The description is a single sentence of approximately 30 words, clearly front-loaded with the main action and without redundancy. Every phrase contributes to understanding 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?

For a tool with two required parameters and an output schema, the description adequately covers its inputs, processing (contrast ratio ranking), and output (WCAG grades and recommendations). No further context is necessary for successful invocation.

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

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

Both parameters are documented in the schema with descriptions, achieving 100% coverage. The description adds semantic context by explaining that the background is the base for ranking and the palette contains candidate foreground colors, enriching the schema descriptions.

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

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

The description uses a specific verb 'return' with the resource 'ranked by contrast ratio' and specifies WCAG grades and recommendations, making its function clear. It distinguishes itself from siblings like accessibility_check by focusing on ranking candidate foreground colors for a given background.

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 comparing multiple foreground colors against a background, but it does not explicitly state when to use it instead of other accessibility or color tools. No exclusions or alternatives are mentioned, so it earns an 'implied usage' score.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds meaningful behavioral context by explaining the tool computes all combinations with specific pass/fail grades and summary, and that it is a batch operation to avoid repeated calls. This goes beyond the annotation without contradicting 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?

Two sentences, front-loaded with the core purpose, and the second sentence gives a clear alternative. No extraneous information or repetition of schema details. Highly concise and well-structured.

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

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

The tool has an output schema (not shown), so return values are already covered. The description fully explains the tool's role and provides context for when to use it, complementing the complete schema and readOnlyHint annotation. Nothing essential is 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%, with the palette parameter already described as an array of hex values with example and min/max constraints. The description only echoes 'palette array' without adding further nuance, 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 accepts a palette array and returns every foreground/background combination with contrast ratios, WCAG pass/fail grades, and a summary. It uses specific verbs and resource, and explicitly distinguishes itself from accessibility_check by noting it should be used instead of calling that tool multiple times.

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

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

The description explicitly says 'Use this instead of calling accessibility_check multiple times for a palette,' providing clear guidance on when to choose this tool over the named alternative. This is direct and actionable.

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

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

Annotations already declare readOnlyHint=true, and the description adds that the tool is deterministic and has no LLM cost, which are meaningful behavioral traits beyond the annotation. It also enumerates return categories, providing transparency about what the tool produces. No contradictions found.

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

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

Two sentences with no redundancy. The first sentence states the action, the second lists outputs and performance characteristics. Every phrase earns its place.

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

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

With an output schema present, the return values are covered. The description explains what the tool does, its inputs, and deterministic nature. The only gap is not explaining the prerequisite 'WCAG matrix' or when to call it relative to siblings, but this is a minor omission for a single-parameter read-only tool.

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

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

Schema coverage is 100%, so the description needn't repeat parameter details. The description mentions 'palette' in context but adds no syntax or formatting details beyond the schema's 'array of hex values'. Baseline 3 is appropriate since the schema fully documents the only 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 converts a WCAG matrix into design-system rules, listing specific outputs (safe pairs, AA-only pairs, etc.). This distinguishes it from sibling tools like accessibility_check or accessibility_matrix by focusing on derived rules rather than validation or raw matrix generation. However, it does not explicitly name a sibling for contrast.

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

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

Usage context is implied: 'Deterministic, no LLM cost' suggests it should be used when a rule-based, inexpensive conversion is needed. But there is no explicit 'use this when' or alternatives listed. It assumes the agent knows to call this after obtaining a palette matrix.

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

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

Beyond the readOnlyHint annotation, the description discloses the exact model (Machado, Oliveira & Fernandes 2009), the fixed severity (1.0), the working colour space (linear sRGB), the clipping flag, and the caveat that this is a model prediction, not individual perception. This is rich behavioural context for a simulation 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?

Two tight sentences front-load the primary behaviour and then add only high-value constraints and caveats. No filler or repetition of the schema.

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

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

For a single-parameter readonly simulation with an output schema present, the description covers the input domain, model, scope, failure/edge behaviour (clipping flag), and interpretation caveat. There are no obvious gaps that would prevent an agent from calling it correctly.

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

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

Input schema already fully documents hex_val with an example, so schema_description_coverage is 100%. The description confirms the hex input by saying 'simulated hex values' but adds little beyond the schema for parameter semantics.

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

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

Description opens with a specific verb and object: 'Return simulated hex values' for three named colour-blindness variants, tied to a named model. It also states exclusions that stop an agent confusing it with accessibility_check 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 clearly scopes when this tool applies: full-severity protanopia/deuteranopia/tritanopia only, and explicitly says anomalous trichromacy and partial severities are not simulated. It does not name an alternative tool, but the exclusion boundaries are explicit enough to guide selection among the accessibility siblings.

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

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

The description goes far beyond the readOnlyHint annotation, detailing evidence-filtering rules (exclusion of reject/stub/blank-source entries), the honest incomplete-result behavior (ok:false, error_code), the application of negative constraints at retrieval time, and special handling for locked_palette. This gives the agent a strong behavioral model.

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 longer than minimal, but every sentence carries distinct information: purpose, deliverable components, supported models, example, use case, filtering rules, failure handling, negative constraints, and locked_palette behavior. It is well-structured and front-loaded, though some sentences paraphrase schema notes slightly.

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 (10 params, multiple filtering behaviors, locked_palette mode, failure modes), the description is remarkably complete. It covers retrieval rules, evidence quality floors, negative constraints, special-case behavior, and model support. The presence of an output schema means return-value documentation is unnecessary, so no additional info is 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?

Although the schema already describes all 10 parameters at 100% coverage, the description adds significant cross-parameter semantics: how 'avoid' and negation phrases in 'concept' affect retrieval, how 'locked_palette' bypasses evidence filtering, how 'minimum_claim_strength' interacts with 'claim_role', and how palette_size relates to the honest failure mode. This goes 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 opens with a specific verb and resource: 'Generate a complete colour direction package for another AI agent or image generation model.' It clearly distinguishes itself from siblings like palette_generate or image_brief by specifying the cross-AI delivery format, including agent brief, tokens, prompt, negative prompt, and lighting notes.

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

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

It provides a clear use case ('Use this to make Colour Memory the colour layer for other AI systems') and an explicit example ('task='luxury hotel bedroom', concept='Ottoman winter luxury', model='midjourney''). However, it does not name alternatives or explicitly say when not to use this tool, so it stops short of full exclusion 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, and the description adds behavioral detail by specifying the return format: fidelity score 0-100, dE2000 distances, match quality categories, and a verdict. This goes beyond the annotation to clarify what the tool computes and reports.

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 focused sentences cover purpose, inputs, outputs, and usage timing with no filler. The structure is front-loaded with the core action, making it easy to scan.

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?

Combined with a rich output schema and readOnly annotation, the description covers the tool's role in the workflow, input options, and output semantics. It leaves little ambiguity about when and how to use it.

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

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

Schema has 100% coverage so baseline is 3. The description adds nuance by indicating that the image can be supplied via URL or base64 (implying either/or), and ties target_palette to agent_brief colour_tokens, which is not explicit in the schema. This extra guidance supports correct invocation.

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 a specific action ('Verify') and a specific resource (AI-generated image colour fidelity against agent_brief). It distinguishes from siblings by referencing agent_brief colour_tokens and dE2000 metrics, making it unique among colour/palette tools.

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

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

Explicitly instructs to use 'after agent_brief + image generation to close the colour loop', providing a clear usage context. It also describes what inputs to supply. However, it does not mention when not to use or name alternative tools, so it falls short of full exclusionary 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 discloses the behavioural process: 'The archive finds the contradiction and Claude writes the one-liner, short story, and tweet,' and shows an example. This adds value beyond the readOnlyHint annotation, which only indicates no side effects. No contradiction with annotations.

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

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

The description is front-loaded with the main purpose, followed by input instructions, an illustrative example, and a use-case sentence. It is compact and 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 details, example output, and target use cases. Since an output schema exists, the return format is already documented. It does not mention n_results explicitly, but the schema covers that, so no significant 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 descriptions already cover all three parameters (100% coverage), so baseline is 3. The description adds semantics by providing concrete examples (e.g., 'love', 'red') and illustrating how they interact (love + red returns Shakespeare's dark green), which helps the agent choose appropriate values.

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: find the most surprising archive colour for a concept and generate a one-liner, short story, and tweet subverting expectations. This specific verb+resource combination and the mention of creative outputs distinguish it from sibling tools like archive_search or colour_story.

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

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

It explicitly says 'Use this for public-facing demos, content, and brand storytelling,' providing a clear when-to-use context. It does not explicitly state when not to use it or name alternatives, but the use case is sufficient.

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

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

Annotations declare readOnlyHint=true, and the description is consistent with a read-only reporting tool. The description adds context about the coverage matrix output and the strategic benefit, but does not disclose additional behavioral traits such as limitations, data sources, or performance characteristics. With annotations covering the safety profile, this is a baseline score.

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

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

The description is four sentences, front-loading the core purpose before output details and usage guidance. Each sentence contributes useful information, though the final sentence about 'beautiful reports' is slightly promotional and could be trimmed without losing essential guidance.

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

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

For a read-only tool with full schema documentation and an output schema, the description provides sufficient context to select and invoke the tool correctly. It explains when to use it, what it returns, and why it matters, making it self-sufficient for an agent to understand its 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%, with both parameters (themes and archives) already well-documented. The description only restates that it takes a list of themes, adding no new semantic detail beyond the schema. Baseline 3 applies because the schema carries the parameter documentation burden.

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

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

The description clearly states the tool reports which themes are well-evidenced versus under-evidenced or missing, with a specific output format. It distinguishes itself from archive_report_brief and brief_forensic by positioning as a pre-flight check, but does not explicitly differentiate from the similarly named sibling archive_evidence_gap.

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

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

The description explicitly instructs to use this tool BEFORE building an archive_report_brief or brief_forensic, providing strong contextual timing. It also explains the rationale (preventing reports that ignore evidence gaps). However, it does not mention when not to use it or name alternative tools like archive_evidence_gap.

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 bar is lower. The description adds useful behavioral context: it detects whether primary_source date falls outside the period, flags known modern archives (RacingSilks, FootballStrips), and returns specific fields (risk level, period_relevance, safe/unsafe phrasing). This goes beyond the annotation without contradiction.

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

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

The description is composed of four purposeful sentences covering definition, detection logic, a use-case example, and output fields. No wasted words, though it is a bit longer than strictly necessary.

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

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

With an output schema and read-only annotation present, the description adequately explains the tool's role and return values. It could be more explicit about expecting entries to contain archive and primary_source fields, but that is inferable from the schema.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds semantic value by explaining that 'archive' values like 'RacingSilks' are known modern sources and linking 'primary_source' to date checking, giving meaning beyond the schema's bare descriptions.

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

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

The description states a specific verb ('check') and resource ('colour entries') and defines the exact risk detection criteria (source date vs period, known modern archives). It clearly distinguishes from sibling tools like archive_coverage_gap or colour_cultural_risk by focusing on anachronism, with a concrete example.

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

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

The description provides clear usage context: 'Essential for historical documents' and a tangible example of a 2011 racing silk being misdated as Georgian. However, it does not explicitly mention alternatives or when NOT to use the tool, which would elevate it to a 5.

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

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

Annotations only declare readOnlyHint=true, and the description adds meaningful behavioral context: it turns absence of evidence into a forensic finding, returns support levels (supported/partial/unsupported), and provides safe agent wording. This goes beyond the annotation without contradicting 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 front-loaded with the core behavior and is about five sentences long. The example is helpful, though the output list is partly repeated between the first sentence and the example, making it slightly less concise than it could be.

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, output, and target workflows. Given that an output schema exists, it does not need to enumerate return fields in detail. It lacks explicit sibling differentiation and limitations, but overall provides enough context for an agent to select and use the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example ('#4A535C' + 'cyanosis in a death chamber') and explains the intent of proposed_claim, but it does not add new parameter-level syntax or constraints 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 opens with a specific verb ('return') and precisely names both inputs ('hex value' and 'proposed claim') and outputs (support decision, missing evidence, source type, safe wording). It also positions the tool as Colour Memory's anti-hallucination endpoint, clearly distinguishing it from siblings like archive_search or archive_coverage_gap.

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

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

The description states the tool is 'essential for museum, documentary, editorial, legal, and forensic workflows' and gives an example scenario. It implies use when an agent has a proposed claim about a colour and needs evidence validation, but it does not explicitly name alternatives or state 'when not to use'.

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

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

Annotations include readOnlyHint: true, and the description aligns by using 'explains' without implying mutation. The description adds meaningful behavioral context by enumerating what the provenance categories are and that confidence and citation format are returned. It goes beyond the annotation but doesn't discuss potential delays or limitations, so a 4 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?

The description is two sentences, front-loaded with the core purpose, then immediately provides usage guidance. Every phrase earns its place with no fluff or repetition.

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 simple input (one string), the presence of an output schema, and readOnly annotation, the description is sufficient. It explains what the tool returns at a conceptual level, when to use it, and how it differs from the closest sibling, making it complete for the complexity involved.

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 single parameter 'colour_name' is fully described in the schema with examples, and the description repeats the notion of a 'named archive colour' without adding additional syntax or format details. Since schema coverage is 100%, the description adds marginal value here.

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

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

The description clearly states the tool explains provenance of an archive colour and specifies the types of provenance (documented fact vs computational derivation vs cultural interpretation) along with confidence and citation format. It also distinguishes this from the sibling tool colour_passport by positioning it as a standalone deep-research tool.

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

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

The description explicitly tells when to use this tool versus the alternative: 'Use colour_passport for a general profile; call this directly for research workflows needing full source-chain detail.' It also names target use cases (museum, documentary, editorial), providing clear context.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context beyond that: 'Two Claude calls total' (resource usage), hard period gates, strict evidence floors ('Never silently relaxed'), and error handling for insufficient results (INSUFFICIENT_PALETTE_RESULTS). It contradicts nothing in the annotations.

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

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

The description is a single dense paragraph that front-loads the core value proposition. It is fairly long, but each sentence adds necessary context (output list, usage priority, alternatives). The output list may duplicate what the output schema already conveys, slightly bloating the text, but it remains well-structured.

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

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

Given the tool's complexity (16 parameters, output schema, minimal annotations), the description provides a complete high-level orientation: purpose, expected outputs, usage guidance, and alternatives. Detailed parameter behavior is left to the exhaustive schema, so there are no critical gaps for an agent to select and call the tool effectively.

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 detailed per-parameter descriptions. The tool description only paraphrases a subset of parameters (title, audience, themes, archives, avoid, n_colours) without adding new semantics or format details beyond what the schema already provides, so the 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 specific, action-oriented claim: 'One-call complete archive research package for a document, PDF, or editorial brief.' It clearly differentiates from siblings by explicitly stating it replaces chaining archive_search + get_colour_card + cliche_breaker + agent_brief, making the tool's unique value unmistakable.

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

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

It gives explicit when-to-use instruction: 'Use this first for any document workflow.' It also names the alternatives it replaces, providing clear guidance on when this tool should be selected over the pointed-to 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 only declare readOnlyHint=true, so the description carries the burden of behavior — and it delivers richly: it guarantees the tool 'never returns a bare empty result' and explains the three response routing states (direct/broadened/redirected) so the agent knows which fallback fired. It also discloses the off-genus exclusion behavior of entity_mode='exact'. No contradiction with the readOnly 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?

Front-loaded with the core purpose and access patterns before any nuance. The match-count examples are concrete and useful. It is long (~230 words) and slightly overlaps the schema's entity_mode explanation, but every section earns its place for a 9-parameter tool; nothing is filler.

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

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

For a complex 9-param tool with an existing output schema, the description covers everything non-inferable: fallback behavior, result routing, entity resolution semantics, and the sibling contrast. Pagination and return values are already handled by schema descriptions and the output schema, so no burden falls on the description there. 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%, so the baseline is 3. The description adds meaning beyond the schema by enumerating the searchable content taxonomy (material, cultural reference, pigment type, historical period) and explaining the consequence of entity_mode on result composition. Some overlap exists — entity_mode and query examples are also in the schema — but the behavioral outcomes (result_path routing, exclusions) genuinely enrich parameter selection.

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?

Opens with a precise verb+resource statement: 'Full-text keyword search across all archive colour names and notes', then enumerates what can be found (name fragment, material, cultural reference, pigment type, historical period). Explicitly differentiates itself from conceptual embedding search, so an agent can tell it apart from query_conceptual and historical_colour_query without opening schemas.

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?

Names the key alternative ('Complements conceptual embedding search with exact keyword matching') and the selection criterion (exact keyword vs semantic). The examples and entity_mode discussion add practical guidance. It stops short of an explicit when-not-to-use statement for every sibling, but the contrast with conceptual search is clear enough for the main routing decision.

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

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

With the readOnlyHint annotation already declaring a safe read operation, the description adds valuable behavioral context: it is deterministic, has no LLM cost, and returns a predefined set of artifact types. This goes beyond the annotation and helps the agent anticipate the tool's reliability and output characteristics.

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

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

The description is three sentences long with front-loaded purpose: the first sentence names the resource, the second lists the exact outputs, and the third adds key behavioral traits (deterministic, no LLM cost). Every sentence earns its place with no wasted words.

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

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

The description thoroughly explains the tool's output scope and purpose. Given the presence of an output schema and full parameter schema coverage, the agent has enough information to select and invoke the tool correctly. It could add more detail on how optional parameters influence the pack, but this is not critical for completeness.

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

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

The schema provides 100% coverage with descriptions for all parameters, so the description does not need to elaborate. It adds no additional parameter semantics beyond what the schema already provides, but schema coverage is sufficient, making this a baseline 3.

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

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

The description clearly states the tool's function: it returns a complete brand asset pack with specific artifacts (CSS variables, Tailwind config, Figma tokens JSON, citation cards, and a Markdown brand guide). This specific verb+resource distinguishes it from sibling tools like palette_export, which focus on single asset 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 usage through phrases like 'Complete brand asset pack' and 'Everything a brand team needs to ship,' suggesting it is for comprehensive brand asset generation. However, it does not explicitly state when to use it vs. alternatives or mention exclusions, so guidance is only implied but not 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?

The description goes far beyond the single readOnlyHint=true annotation. It discloses that the tool is synchronous and deterministic with no model call, reveals that interpretation was historically performed inside the tool without disclosure and the resulting 43-45s latency, and explains the continuation mechanism (returns palette_verdict.continuation.arguments to forward verbatim). It also discloses the PARTIAL/INSUFFICIENT audit_status behavior when site_evidence is inadequate and that the tool itself does not browse. This is exactly the kind of historical and operational transparency an agent needs. No contradiction with readOnlyHint=true — a deterministic synchronous computation is consistent with read-only.

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?

This description is long, but every sentence carries operational information an agent cannot infer from the schema or annotations. The structure is well-designed: core purpose front-loaded, then COMPUTED HERE, then NOT COMPUTED HERE, then the live-site workflow, then downstream routing. Capitalized section markers ('COMPUTED SYNCHRONOUSLY', 'NOT COMPUTED HERE', 'FOR A LIVE-SITE BRAND AUDIT') make the dense content scannable. It loses one point only because some sentences could be tightened without losing meaning; at this complexity level the length is otherwise justified.

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 6 parameters, nested objects, and an output schema, this description is remarkably complete. It covers the computation model, what is deliberately excluded and why, the continuation handoff to palette_verdict, the live-site evidence requirements with named status codes, the downloadable deliverables (PNG, PDF, ASE, JSON, CSS), and the anti-pattern to avoid (presenting archive anchors as recommendations). Since an output schema exists, return values need not be fully re-explained, but the description still names the key output keys. Nothing needed for correct invocation is 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 coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema. For site_evidence it explains the workflow prerequisite (inspect rendered pages first), the minimum evidence for a FULL audit (homepage, about, one deep page, rendered evidence from at least two), and the consequence of shortfalls (PARTIAL/INSUFFICIENT status). It also adds behavioral guidance about the palette parameter ('Never present the archive anchors a colour was derived from as the colours you are recommending'). It does not add much for market, medium, use_case, or brand_category, which the schema already covers adequately.

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

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

The opening sentence states a specific verb and resource ('colour brand audit') and immediately narrows scope with 'fully deterministic' and 'no model call of any kind.' The description then enumerates precisely what is computed (WCAG matrix, cultural risk, CSS variables, Tailwind config, design tokens) and what is not (palette interpretation), which sharply distinguishes it from siblings like palette_verdict, accessibility_matrix, and cultural_risk_assessment. Even the title 'Complete Brand Colour Audit' is descriptive rather than tautological.

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?

This is exemplary usage guidance. It explicitly says the tool 'Replaces chaining accessibility_matrix + cultural_risk_assessment' and that palette_verdict is 'an explicit, optional second call rather than a hidden one,' naming both the alternatives and the relationship. It gives conditional instructions for the live-site case ('inspect representative rendered pages FIRST... a CSS scrape alone is not an audit'), and it routes downstream to palette_finalize with concrete conditions. An agent knows exactly when to call this tool, what to do beforehand, and what to call next.

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 carry readOnlyHint=true, and the description is consistent with a pure analysis tool. It adds genuine behavioral detail beyond the annotation: the verdict taxonomy (strong/viable/contested/collision), the 0-100 distinctiveness scale, and the fact that it consults archive context per colour. The provenance-based scoring caveat lives in the schema rather than the description, but the description discloses the core analytic behavior well.

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

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

Three sentences with zero filler: purpose question, input summary, output list, usage timing, and replacement value. Dense but readable, and the most decision-relevant information (what it returns, when to use it) is front-loaded before the output enumeration.

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 complex tool with 7 parameters and an output schema, the description covers the essentials: purpose, inputs, outputs, and when to invoke. The presence of an output schema relieves the description of explaining return-value structure. Minor gaps: the meaning of 'archive context for each colour' is opaque, and the verified-vs-estimated provenance behavior is only in the schema — an agent reading only the description would miss a key scoring caveat.

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 examples (e.g., '#D4A829', 'UK luxury food retail', provenance enums). The description restates the input set at a summary level but adds no new semantic information beyond the schema. Baseline 3 is correct since the schema carries the full burden.

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?

Opens with a purpose-framing question ('Can this brand own this colour against these competitors in this market?') that captures the exact job. Enumerates concrete inputs and outputs (CIEDE2000 distance, distinctiveness score, ownership verdict) that clearly differentiate it from sibling tools like colour_compare or colour_metrics — this is an ownership/strategy assessment, not a numeric comparison.

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

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

Provides explicit timing guidance: 'Use before committing to a brand colour in a competitive market.' Also states it 'replaces manual colour distance checks and competitor palette analysis,' which frames the decision context. However, it never names a sibling alternative or states when NOT to use it (e.g., when only raw CIEDE2000 numbers are needed), so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds value by explaining it reads a 'frozen brand_ref snapshot' and 'never re-runs generation or mutates anything,' plus the behavior of omitting claim_ids. This goes beyond the annotation hints.

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

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

Three sentences, front-loaded with the primary action, each sentence earning its place. It's concise but information-dense, with no filler.

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

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

With an output schema present and full parameter coverage, the description doesn't need return-value detail. It covers behavioral guarantees, input constraints, and sibling relationships, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying that claim_ids are 'returned inline on every colour' by sibling tools, and that brand_ref/project_id are mutually exclusive ('exactly one'). This is useful context 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 opens with a specific verb and resource: 'Resolves claim_id values ... into their full claim record.' It clearly lists what the record contains and references sibling tools (brand_guideline_specify/select) that produce the claim_ids, distinguishing it from 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 clear context: use with claim_ids from brand_guideline_specify/select, omit to get all claims, and accept brand_ref or project_id exactly one, same as brand_guideline_pdf. It doesn't explicitly state when not to use it, but the guidance is sufficiently specific.

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 read-only and idempotent, but the description adds crucial behavioral detail: variable page count, omission of empty sections, provisional preview labeling, and the guarantee never to mutate or recompute. This goes far beyond the structured annotations and enriches the agent's understanding.

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

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

The description is dense but every sentence contributes a substantive detail about output composition or behavioral guardrails. It is longer than average but contains no filler or repeated information, earning a strong score despite its length.

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

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

With rich annotations, an output schema, and a description that covers output content, variable behavior, input prerequisites, and safety guarantees, the tool is fully specified. An agent has all necessary information to decide when to use it and what to expect.

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

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

Schema coverage is 100% with per-parameter descriptions, so the baseline is 3. The description adds the essential exclusivity rule ('exactly one of brand_ref or project_id') and traces brand_ref provenance to brand_guideline_specify/select, providing context not captured 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 opens with a specific verb ('Renders') and resource ('client-facing brand colour standard PDF') derived from an existing brand_ref. It clearly differentiates from sibling tools like brand_guideline_specify and brand_guideline_select by focusing on rendering an existing snapshot rather than creating or selecting.

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

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

The description states the prerequisite ('from an existing brand_ref'), gives the exclusivity constraint ('Accepts exactly one of brand_ref or project_id'), and explicitly names what it never does ('never re-runs brand_guideline_specify, never rematches an archive'). It stops short of naming alternative tools for those scenarios, but the guidance is clear and actionable.

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

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

The description adds meaningful behavioral detail beyond the annotations: it creates a revised brand_ref with the same reference but a new version underneath, like a versioned house_ref. It also scopes behavior by stating there are no accounts or reviewer states yet, which helps set expectations for side effects and workflow position.

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 dense sentence that front-loads the core action and includes only useful qualifications. The versioning comparison and the explicit non-inclusion of approval workflow earn their place because they clarify behavior and boundaries without padding.

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 6-parameter tool with full schema coverage and an output schema, the description provides the missing workflow context: where the inputs come from, what the output represents, and what this stage does not include. Nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds high-level framing by naming selected candidate, locked colours, and suppressed claims, but it doesn't add meaning beyond what the property descriptions already convey; the brand_ref/project_id distinction remains explained only 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 records a manual brand colour decision: which candidate was chosen, which colours to lock, and which claims to suppress. It ties the action to the sibling brand_guideline_specify tool and distinguishes itself as the decision-recording counterpart, so an agent can tell it apart from brand_guideline_status or brand_guideline_claims.

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: use this after brand_guideline_specify has produced a candidate, and it notes this is decision-making, not a full approval workflow. It does not explicitly enumerate alternates or when-not-to-use conditions, but the connection to specify and the exclusion of approval states provide solid 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?

Annotation Contradiction: the description states the call creates server-side state — it returns project_id/current_version, creates a second project when continue_project_id is omitted, and leaves generation running server-side — while the annotations declare readOnlyHint=true. An agent trusting the annotation would assume zero side effects. Apart from this conflict, the prose itself is exemplary: it discloses the ~55s async race window, persistent generation that is 'never lost', polling discipline (poll_after_seconds), and 24h brand_ref validity.

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 long but earns its length: three paragraphs with distinct topics (outputs/follow-ups, versioning, async timing), with the core value proposition front-loaded in the first sentence. Minor redundancy ('keeps running server-side regardless, and is never lost') and slightly convoluted phrasing ('the response's own claim_detail_available_via field') keep it from a 5.

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 8 params, nested objects, five palette_input modes, an async dual-path, and a multi-tool workflow, the description is nearly complete: outputs, follow-up chain, versioning, and polling are all specified, and an output schema covers return values. Small residual gaps — mode prerequisites (e.g., mode=image requires a prior ingest_image call, mode=archive needs a valid archive name) and failure semantics — prevent a 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?

The description adds real meaning for continue_project_id by giving concrete continuation examples ('Make it warmer', 'change the secondary', 'render the PDF again'), which is genuinely additive beyond the schema. However, it does not compensate for the roughly 37% of parameters left undocumented in the schema (accessibility_target, tone, language, and object-level descriptions for preferences/identity_assets/output_preferences), so those rely on names and enums 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 opening sentence states a precise verb and resource: 'Generates the case for a brand's colours, not just the colours themselves' — three archive-grounded candidate palettes, scored for distinctiveness, checked for accessibility, and labelled with claim legitimacy. It clearly positions this as the 'case-making' specify step, distinguishing it from obvious siblings like palette_generate, brand_guideline_claims (claim resolution), and brand_guideline_select (recording the choice).

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 sequencing and alternatives are given: follow with brand_guideline_select to record the choice, resolve claim_ids via brand_guideline_claims, and poll via brand_guideline_status with brand_job_ref when the slow path returns processing. The versioning rule states exactly when to pass continue_project_id (refinements, with concrete examples) and when not to ('Start a new project only when the customer asks for a genuinely separate brand').

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 read-only, idempotent, non-destructive. Description adds behavioral context: it's an in-process lookup, never re-runs generation, and details all possible return states including error handling (BRAND_JOB_NOT_FOUND). This goes beyond the annotations and gives full 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?

The description is a single dense paragraph but every clause adds value: purpose, conditions, read-only nature, return shapes, error behavior, and pointers to related tools. It is front-loaded and free of filler.

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

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

The description fully covers all possible outcomes (processing, complete, failed, not found) and how to proceed with the returned brand_ref. It references the output schema implicitly and the sibling tool family, making it complete for an agent to 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 a clear parameter description. The tool description adds semantic context by explaining the parameter's origin ('returned by brand_guideline_specify') and its role in a race-to-complete scenario, which is not 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 resolves a brand_job_ref from brand_guideline_specify when its race-to-complete window elapsed. It uses a specific verb ('Resolves') and resource ('brand_job_ref'), and distinguishes itself from siblings by focusing on status retrieval, not generation or full detail retrieval.

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

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

The description explicitly states when to use it: when brand_guideline_specify's race-to-complete window elapsed before generation finished. It also provides guidance on alternatives by directing the user to use brand_guideline_select/brand_guideline_pdf/brand_guideline_claims for full detail, and clarifies it never re-runs generation.

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

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

With readOnlyHint annotation already conveying safety, the description adds useful behavioral context: it explains the tool is a composite that aggregates outputs from multiple sub-tools and mentions the internal 'Two Claude calls' detail. It also lists the full set of outputs, giving transparency into what the report includes. No contradiction with annotations is present.

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 structured with clear 'Input:' and 'Output:' sections and a final usage sentence. It is front-loaded with the main concept, and while the output list is long, each item is relevant and earns its place. It is not verbose or repetitive, and it avoids unnecessary 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 (7 parameters, output schema, nested objects), the description covers inputs, outputs, and usage guidance, making it reasonably complete. The existence of an output schema means it does not need to detail return structures. It could optionally mention more about prerequisites or limitations, but overall it provides sufficient context for an agent to decide and 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?

The input schema has 100% coverage, with each parameter described in detail. The description itself lists the inputs ('hex + brand context + markets + medium + product type') but adds little semantic value beyond grouping them. It does not provide additional format, constraints, or relationships to outputs that aren't already in the schema. Thus, a baseline score of 3 is appropriate.

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

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

The description clearly states it is a 'complete brand colour intelligence report' with a specific verb ('report') and resource ('brand colour intelligence'). It explicitly differentiates from sibling tools by naming them: 'colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief', and positions itself as the composite alternative. This is a strong, specific purpose statement.

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

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

The description provides explicit usage guidance: 'Use this instead of chaining ... separately' and mentions 'Two Claude calls total. One complete response.' This tells the agent when to choose this tool over chaining individual tools. However, it does not explicitly state when NOT to use it (e.g., when only one specific output is needed), so it falls short of a perfect 5.

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

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

Beyond the readOnlyHint annotation, the description discloses that the call is deterministic and has no LLM cost, which sets cost and behaviour expectations. It also states that the result already carries the rendered palette and download files (PNG, PDF, ASE, JSON, CSS) and instructs the agent to show them to the customer. The guardrail about archive anchors and the palette_finalize handoff add meaningful operational context that annotations do not provide.

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

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

The description front-loads the core purpose and output list in the first sentence, then layers cost/determinism, embedded deliverables, presentation instructions, and a cross-tool handoff. Each sentence earns its place: the determinism note, the 'show them to the customer' directive, and the palette_finalize routing all affect agent behavior. It is long but appropriately so for a complex aggregate tool.

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

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

Given the tool's complexity—5 parameters, output schema, many siblings—the description is operationally complete. It explains what the tool returns, that it is deterministic, that downloads are embedded, how to present results, and what to do if the agent selects its own palette. Parameter details are already in the schema, and return structure is covered by the output schema, so nothing critical is 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?

The input schema covers all 5 parameters with 100% schema description coverage, so the baseline is 3. The description does not add extra meaning for market, medium, palette, use_case, or brand_category. Since the schema already documents these parameters well, the description does not need to compensate and no deduction is warranted.

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 'Complete brand colour system in one call' and then enumerates concrete deliverables such as colour roles, light/dark role maps, typography guidance, usage rules, design tokens, and citation cards. This gives the agent a specific verb, resource, and scope. It also references palette_finalize as a distinct follow-up, which helps separate this aggregate tool 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 clearly indicates when to use the tool—when a complete brand colour system is needed in one call—and gives an explicit alternative: if the agent chooses its own final palette, it should call palette_finalize once with those colours. It also provides concrete behavioural guidance such as 'Never present the archive anchors... as the colours you are recommending.' It stops short of listing exclusions for narrower palette tasks, but the routing is clear.

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

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

The readOnlyHint annotation already signals safe read-only behavior, and the description adds value by specifying the exact kind of data returned (hex, archive, provenance, cultural notes). It does not introduce contradictions or hidden side effects, making the behavior clear for a lookup 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 a single, well-structured sentence that front-loads the primary action and outcome. It contains no filler or repetition, earning its place efficiently.

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

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

Given the presence of an output schema, a readOnlyHint annotation, and detailed parameter descriptions, the concise description is largely sufficient. It could benefit from a note about fallback behavior when a name is not found or when to prefer slug over name, but the current coverage is adequate for straightforward 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?

The input schema provides 100% coverage with clear descriptions for both parameters (name and slug), including the suggestion that slug is preferred. The tool description adds no additional parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('look up') and resource ('named colour') and lists the return contents (hex, archive, provenance, cultural notes). It distinguishes itself from colour_* siblings by focusing on details by name, though it doesn't explicitly differentiate from similar lookup tools like colour_passport.

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

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

The description implies when to use the tool ('when you have a named colour'), but it does not provide explicit guidance on when to use it vs alternatives or mention prerequisites like using archive_search to obtain a slug. No exclusions or alternatives are noted.

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 readOnlyHint=true already indicates a safe read operation. The description adds meaningful behavioral context by specifying the tool returns harmony type, clash warnings, contrast summary, and deployment rules. No side effects are disclosed because none exist, and this is consistent with 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 one sentence, front-loaded with the action verb 'Assess' and the resource, followed by a compact list of return categories. Every clause adds value and there is no redundancy or filler.

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

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

With only two well-documented parameters, an output schema present, and a read-only annotation, the description sufficiently covers the tool's purpose, scope, and outputs. The return details are handled by the output schema, and the description provides the needed situational 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%: both parameters (colours and context) are described with details like hex values and allowed contexts. The description repeats this information without adding new semantics such as default behaviour, hex format specifics, or validation rules. Baseline 3 applies.

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

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

The description uses the specific verb 'Assess' and identifies the resource as '2-5 colours as a combination' for a defined context list (UI, data viz, fashion, interior, print, branding). It enumerates return types (harmony type, clash warnings, contrast summary, deployment rules), distinguishing it from sibling tools like colour_compare or palette_generate.

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

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

The description clearly states when to use the tool: evaluate a combination of 2-5 colours for a given context, listing six specific contexts. It does not name alternative tools or state exclusions, but the context list and 'combination' scope imply appropriate usage. This is clear context without explicit 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 annotation readOnlyHint=true already discloses non-destructive behavior. The description adds meaningful behavioral context by enumerating the return content — LRV, chroma, hue angle, warmth, CIEDE2000 distance, and cultural context — and notes the tool's decision-support function, going 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?

Three sentences, front-loaded with the core action, followed by output details and usage guidance. Every sentence contributes distinct information: what it does, what it returns, and when to use it. No filler or repetition.

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 a simple 2-parameter interface and an output schema present, the description is fully sufficient. It explains the tool's purpose, output categories, usage contexts, and explicitly rejects the harmony-tool role. An agent can confidently select and invoke this tool without 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 coverage is 100%, with both hex_a and hex_b described and example formats provided. The description phrases them as 'any two hex values,' reinforcing the relationship between parameters, but does not need to add further detail since the schema already carries the semantic load.

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 specific verb and resource: 'Deep perceptual and semantic comparison between any two hex values.' It lists concrete output dimensions and clearly distinguishes itself from harmony tools with 'Not a harmony tool — this is a decision and reasoning tool,' setting it apart 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?

Provides explicit guidance: 'Use when choosing between two colours or explaining why one works better than another.' It also states an exclusion ('Not a harmony tool'), which helps an agent decide against this tool when harmony-related tasks arise.

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 context beyond annotations by explaining the tool handles both hex and palette inputs and that it serves as a component of colour_passport. No contradictions, and it clarifies scope without needing to restate safety since annotations cover that.

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

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

Two sentences, front-loaded with purpose, then a concise usage comparison. Every sentence carries meaning with zero filler.

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

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

Given the readOnly annotation, output schema, and full parameter coverage, the description sufficiently addresses what the tool does, when to use it, and how it relates to colour_passport. It is complete for an agent to select this tool among many colour-related 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 descriptions cover all 3 parameters at 100%, so the baseline is 3. The description connects 'hex value or palette' to the hex/palette parameters but does not add per-parameter syntax or nuance beyond what the schema already provides.

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

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

The description clearly states the tool assesses cultural risk for a hex value or palette, enumerating specific dimensions (symbolic weight, taboos, religious associations, market flags). It explicitly distinguishes itself from colour_passport by positioning as a component and direct-call for palette-level risk checks.

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

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

Provides explicit guidance: 'Use colour_passport for a general profile; call this directly for palette-level risk checks or when cultural risk is the only thing being asked about.' This names an alternative and gives concrete decision criteria.

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

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

Annotations only provide readOnlyHint=true, but the description adds substantial behavioral context: the result already contains the rendered palette and PNG/PDF/ASE/JSON/CSS downloads, the agent must show them, and it must never present archive anchors as recommended colours. This goes well beyond the read-only safety signal and tells the agent what to do with the output.

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?

All four sentences carry distinct, necessary information: what the tool produces, when to use it instead of colour_passport, what the result contains, and the critical finalization/misrepresentation guardrails. No filler or repetition; the key scoping statement is front-loaded.

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

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

Given one well-documented parameter, a readOnlyHint, and the presence of an output schema, the description is complete. It covers selection criteria, expected result contents, customer-facing display behaviour, and the follow-up action to palette_finalize. Nothing essential is missing 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?

Schema description coverage is 100% because the single required parameter `hex` already has a clear description and example ('#4A2A50'). The tool description adds no new parameter-level detail beyond calling it a 'single hex colour,' so the baseline of 3 is appropriate.

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

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

The description names a specific resource ('single hex colour') and a specific outcome ('Compact semantic fingerprint'), and immediately distinguishes it from colour_passport: 'This is one component of colour_passport.' It is clear which sibling this tool is and is not, without needing to open the schema.

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

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

The description explicitly states when to use this tool: 'use colour_passport for a general colour profile; use this only when the user explicitly wants the fingerprint format alone.' This is a direct usage criterion separating it from the closest sibling. It also gives a downstream rule: call palette_finalize if you choose your own palette from this evidence.

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?

Even with readOnlyHint annotation, the description adds substantial behavior: verdict types (yes/conditional/avoid), risks, required actions, illuminant analysis, substrate notes, and recommended alternatives. It also discloses methodology (CIEDE2000 archive matching and Claude material knowledge), going well 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, with a clear front-loaded purpose and a compact list of returns. The final 'Backed by...' sentence adds credibility but is not purely functional, and the four examples are useful though slightly expand length.

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

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

The description covers purpose, output categories, methodology, and concrete usage scenarios, and is paired with a full output schema and readOnlyHint. It is sufficiently complete for correct invocation despite the tool's complexity and the large sibling set.

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

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

Schema description coverage is 100% for all 5 parameters, so the baseline is 3. The description does not add parameter-specific syntax or details beyond what the schema provides, though its examples reinforce valid substrate and orientation values.

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 whether a hex colour can be safely specified for a physical application, using a specific verb and resource. It distinguishes itself from colour_verdict or colour_metrics siblings by focusing on physical/material safety rather than generic colour 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?

It provides clear usage context: use when assessing safety for a physical substrate, reinforced by concrete examples like 'ultramarine on lime plaster' and 'lead white on exterior timber'. However, it does not explicitly mention alternatives or exclusions, which prevents a 5.

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

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

Beyond the readOnlyHint annotation, the description reveals important behaviors: hay_contrast snaps to Hay's nearest named hue, returns covered:false with no invented partner for tertiary regions, and the result already includes rendered palette downloads. It also warns against presenting derived archive anchors as recommendations. This significantly exceeds annotation-level 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?

Every sentence earns its place: the first defines the core function, the second explains the special case, the third clarifies output, the fourth warns about a common misuse, and the fifth routes to the correct follow-up tool. There is no fluff or repetition, and the most important information is front-loaded.

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

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

Given the tool's complexity (a special historical contrast mode with edge cases) and the presence of an output schema, the description covers everything an agent needs: available harmony types, hay_contrast's unique behavior, output deliverables, customer presentation, and the exact condition for calling palette_finalize. No critical usage detail is 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 baseline is 3. The description adds meaningful context for harmony_types, especially hay_contrast's snapping behavior and its edge-case covered:false result. It does not add new semantics for the hex parameter, but the extra behavioral detail for the special harmony type justifies a score above baseline.

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

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

The description opens with a specific verb and resource: 'Return complementary, triadic, analogous, and split-complementary harmonies matched to named archive colours.' It clearly distinguishes this tool from siblings by naming the exact harmony types and highlighting the unique hay_contrast mode. The reference to palette_finalize as a downstream step further clarifies its role in the workflow.

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

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

The description explicitly differentiates hay_contrast from fixed-angle types, explaining when it snaps and when it returns covered:false. It also gives direct routing guidance: 'If you go on to choose a final palette OF YOUR OWN from this evidence, call palette_finalize once...' and instructs the agent to show the downloaded result to the customer. This is actionable, unambiguous usage 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 only state readOnlyHint: true. The description adds valuable behavioral context by disclosing that outputs are 'backed by the nearest archive colour's cultural provenance' and that the tool is tunable by audience and tone. This goes beyond the annotation's simple safety hint and explains what the tool actually does with inputs.

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 that front-load the primary action and outputs, followed by concise use cases. No wasted words; every sentence earns its place. This is an example of efficient, well-structured tool documentation.

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 generative nature, the description lists all output types (hook, story, tweet, image prompt, follow-up questions) and presents relevant usage scenarios. An output schema exists to detail return values, so the description does not need to cover those. The description is complete for an agent to decide 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 coverage is 100% with clear descriptions for hex, tone, and audience. The description's mention of tunable audience/tone examples ('general public, designers, historians, children') largely mirrors the schema's own examples. It adds minimal extra meaning, such as 'any hex colour', which does not significantly exceed what the schema already conveys.

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 specific verb ('Generate') and lists concrete outputs (hook sentence, three-sentence story, tweet, image prompt, follow-up questions) for a hex colour. It clearly distinguishes this tool from siblings like colour_story or colour_namer by focusing on multi-format content generation grounded in archive provenance.

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

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

The description provides explicit use cases ('Use to make archive colours shareable, to generate content, or to power a public-facing colour chat experience'), giving clear context for when to invoke it. It does not explicitly mention when not to use it or name alternatives, so it falls short of a 5 but is well above vauge 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 readOnlyHint annotation already declares this as a safe operation. The description adds value by specifying the brand scope ('Farrow and Ball and Little Greene'), which is not in the annotation. However, it does not clarify whether the tool supports additional brands beyond these two, and the 'including' wording could be ambiguous. The behaviour of matching a hex to a named colour 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 a single sentence that is front-loaded with the verb and resource, containing no filler. It efficiently conveys the essential 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?

The tool has low complexity, a complete input schema, an output schema, and a readOnlyHint annotation. The description covers the core purpose and specific brands. It is slightly ambiguous about whether other paint brands are supported, but the overall context is sufficient for an agent to understand what the tool does and what it 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 description coverage is 100%, with each parameter already having clear descriptions (n: 'Number of matches', brand: 'Optional brand filter', hex_val: 'Hex value'). The description does not need to add parameter details. It does not go beyond the schema, but that is acceptable given the high coverage.

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

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

The description clearly states the tool's function: 'Find the nearest named colour in commercial paint systems including Farrow and Ball and Little Greene.' This uses a specific verb ('find') and resource ('nearest named colour in commercial paint systems'), and explicitly names the included brands, which distinguishes it from sibling tools like colour_namer or colour_compare that may handle generic colour naming or comparison.

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 matching a hex value to a commercial paint system colour, which is clear context. It does not explicitly list alternatives or when-not-to-use, but the mention of 'commercial paint systems' and specific brands provides sufficient guidance for selection among the many sibling palette/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?

The readOnlyHint annotation already signals safety, and the description adds meaningful behavioral detail: the values are estimated, limited to what a hex can support, and computed under two standard illuminants. It also calls out limitations like thermal performance and measured LRV, which helps an agent set user expectations without contradicting the annotations.

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

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

The description is compact, front-loaded with the core purpose, and every sentence earns its place: first states what it returns, then notes its limitations, then routes to the sibling. The detailed list is dense but not padded.

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 one parameter, readOnlyHint annotations, and an output schema, the description covers everything needed to invoke the tool correctly: what it computes, what it cannot compute, and when to prefer colour_passport. No critical context is 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 hex_val. The description reinforces that the input is a single display colour and notes hex limitations, but it does not add parameter-level details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description begins with a specific action and resource: 'Returns numeric metrics derived from a single display colour' and enumerates exact quantities (LRV, luminance, CIELAB lightness, chroma, hue angle, Bradford corresponding colours). It also explicitly distinguishes itself from colour_passport, so an agent can reliably tell this tool apart from a key sibling without opening the schema.

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 when-to-use guidance: 'Use colour_passport for a general colour profile; use this only when the user explicitly wants isolated numeric values.' This explicitly names the alternative and states the condition that selects this tool, leaving no ambiguity about routing.

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 readOnlyHint=true is consistent with the description, which adds rich behavioural context: the CIE Lab subtractive model, perceptual accuracy, and the nature of the output (nearest archive match with cultural context). This goes well beyond what the annotation alone conveys.

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

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

Four sentences, each earning its place: the core function, the output, the model reinforcement, and a concrete example. It is front-loaded with the most important information and has 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?

The description covers purpose, method, output, and a worked example. Given the existence of an output schema and annotations, it is complete without needing to detail return structures or safety profile.

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 semantic value through the example (Prussian Blue + Yellow Ochre gives a muted green), illustrating the intended meaning of the hex inputs as pigment colours. This helps the agent understand the parameters beyond their raw format.

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

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

The description states exactly what the tool does: simulate subtractive mixing of two colours in CIE Lab space, distinct from RGB screen blending, and returns the mixed hex plus nearest archive match. This is a specific verb+resource+method and distinguishes it from other colour tools.

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

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

It explicitly notes 'not RGB screen blending', which is a clear when-not situation. However, it does not name alternative tools for additive mixing or colour comparison, leaving the guidance slightly implicit. The example provides a concrete use context but no explicit alternatives.

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

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

Annotations declare readOnlyHint=true, so the safe, read-only nature is already known. The description adds useful behavioral context beyond that: names are 'archive-verified' and 'grounded in a real archive source,' and it lists the naming styles. It does not contradict annotations, and it supplements them with meaningful details about the tool's behavior.

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

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

The description is three concise, front-loaded sentences. The first sentence states the core action, the second lists options, and the third explains the unique value and primary use case. There is no filler or repetition; every sentence contributes.

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, 1 required) and the presence of an output schema, the description is adequately complete. It covers purpose, style options, archive grounding, and a concrete use case. It could mention when to prefer alternative tools, but that is more of a usage guideline matter.

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 the style options ('geographical, poetic, material, literary, botanical, industrial, or mixed'), which mirrors the schema's style property but adds no extra meaning. It does not elaborate on parameters like market, n_names, or product_type, relying on the schema to carry that information.

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

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

The description clearly states the tool's function: 'Generate memorable, archive-verified colour names for any hex value.' It uses a specific verb ('Generate'), a specific resource ('colour names'), and adds scope ('for any hex value') and differentiators ('archive-verified', 'grounded in a real archive source'). This distinguishes it from sibling tools like colour_card or palette_generate, which focus on palettes or analysis rather than 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 provides a clear context: 'The core of the Shopify product naming use case,' implying when the tool is appropriate. However, it does not explicitly mention when not to use it or compare it to sibling naming tools like ecommerce_namer, so it lacks exclusions or alternatives.

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

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

Annotations declare readOnlyHint=true, so no destructive behavior needs disclosure. The description adds value by explaining the tool returns a canonical, exhaustive dataset and gives concrete examples, which helps set expectations. It doesn't discuss rate limits or auth, but for a read-only tool with a rich output schema, the disclosure is sufficient.

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

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

The description is longer than average but well-structured: definition, content summary, usage guidance, and examples. Every sentence contributes, though the list of data categories could be slightly more compact. It is appropriately detailed for a complex tool with many optional parameters.

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

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

Given the tool's complexity, the description provides enough context to understand its role, what it returns, and when to use it. The output schema covers specific return values, and examples ground the behavior. Minor missing context like default archive count or batching behavior is already in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description doesn't add parameter-level detail, but it doesn't need to; the schema already explains hex, hexes, n_archive, include_physics, and include_cultural with defaults and examples.

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

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

The description opens with 'Canonical single-call colour truth object' and 'Returns everything known about a hex value', clearly stating the tool's purpose and scope. It explicitly distinguishes itself from siblings by naming colour_dna, archive_provenance, colour_cultural_risk, and colour_metrics, and positions itself as the foundational call ('Every other tool is built on this data').

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

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

Provides clear guidance on when to use: 'Use this as the foundation call when you need the complete picture.' It also explains when not to chain separate tools by stating it 'Replaces chaining colour_dna + archive_provenance + colour_cultural_risk + colour_metrics separately', offering a direct alternative comparison.

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

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

Annotations only provide readOnlyHint=true. The description adds behavioral details such as the 20-value limit, automatic deduplication, and the full set of returned fields (colour science, archive anchor, evidence grade, etc.). This goes beyond the annotation without contradicting 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 compact and front-loaded. The first sentence names the tool as a batch version, then immediately states the limit and return behavior. Every sentence adds value with no redundant wording.

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 full schema parameter descriptions, the description covers the core purpose, constraints, deduplication, and usage scenarios. It is complete for a batch lookup tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a maximum batch size of 20 hex values and states that deduplication occurs, which are constraints not present in the schema. It does not discuss the optional parameters, but those are fully described 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 explicitly states it is the 'Batch version of colour_passport' with a clear verb 'submit' and resource 'hex values', and lists the returned product. It distinguishes itself from the singular colour_passport sibling by batching up to 20 values.

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 explicit use cases: 'multi-colour workflows, Figma palette analysis, or any case where calling colour_passport separately for each colour would be slow.' This provides clear context and names the alternative (colour_passport), though it does not explicitly list 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?

Even with readOnlyHint=true, the description goes far beyond the annotation by explaining that results are separated by relationship_class to prevent mistaking computed distance for historical assertion, that every edge carries an inline 'does_not_mean' caveat, and that missing relationships are true negatives. It also discloses the current population state (348 Wada plates). This is rich, honesty-promoting behavioral disclosure.

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 dense but every sentence earns its place: framing question, population context, relationship-class distinction, caveat behavior, true-negative semantics, and input source guidance. It is front-loaded with the core question and strongly structured for agent 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 the tool's complexity, the output schema, and the annotations, the description covers everything an agent needs to call it correctly: what the graph contains, how relationship classes are separated, what caveats accompany edges, how to interpret empty results, and where to obtain valid IDs. No critical context is 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?

The schema already covers all three parameters at 100%, so the baseline is 3. The description adds meaningful context for record_id (stating its source) and for include_computed by clarifying what 'computed' relationships mean via DETERMINISTIC_STRUCTURAL. include_unresolved gets no description-level elaboration, but the schema carries its own explanation.

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 a specific verb and resource: a one-hop lookup over Colour Memory's stored relationship graph, returning edges grouped by relationship_class. It gives concrete examples of SOURCE_ASSERTED and DETERMINISTIC_STRUCTURAL relationships, which sharply defines the tool's job. However, it does not explicitly distinguish itself from sibling tools like why_connected, so it stops short of a perfect 5.

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 usage context: this is a one-hop graph lookup, and it explicitly warns that an empty result is a true negative, not an error. It also tells the caller where to get valid record_id values (archive_search or colour_card). It does not name alternatives or state when not to use this tool, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, establishing the safe read-only nature. The description adds valuable behavioral context by explaining that the name source is archive-grounded and uses dE2000 distance for color matching, which helps the agent anticipate how results are produced. 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 two sentences with no redundancy. The first sentence front-loads the action and lists all output formats; the second provides the naming source. Every word earns its place, making it highly efficient.

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

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

The description, combined with a complete input schema and the presence of an output schema, provides sufficient context for a read-only transformation tool. It lacks explicit edge-case handling (e.g., invalid hex) and prerequisites, but these are not critical given the tool's simplicity and the schema coverage.

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%, as both hex and archive parameters are already described in the input schema. The description mentions 'hex value' and 'Archive-grounded' which loosely connects to the archive parameter, but it adds no new parameter-specific meaning beyond what the schema already provides.

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

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

The description states a specific action (return every developer token format) for a given hex value, listing concrete outputs (CSS variable, kebab-case, camelCase, PascalCase, Tailwind class, TypeScript const, SCSS variable). This clearly distinguishes it from sibling tools like colour_namer by focusing on developer token formats and mentioning archive-grounded naming with dE2000 distance.

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 developers need naming conventions from a hex value, but it does not explicitly state when to prefer this tool over alternatives or provide exclusions. No alternative tools are mentioned, so usage context is only implied, not 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?

The annotation already indicates read-only behavior, and the description does not contradict it. The description adds valuable context by specifying what the narrative contains (history, civilisations, archive names) and provides a concrete example. It does not discuss potential latencies or edge cases, but the output schema and read-only hint lower the burden.

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: what it does, when to use it, and an example. It is concise, front-loaded with the core purpose, and every sentence earns its place. 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 a complete input schema, an output schema, and a read-only annotation, the description needs only to convey the tool's purpose and when to use it. It does so effectively, including a rich example. There is no significant missing information for a tool of this moderate complexity.

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

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

The input schema has 100% description coverage for both parameters, so the baseline is 3. The description does not add much beyond the schema—it repeats the hex requirement via the example but does not elaborate on n_archives or how it affects the output. The schema already documents the parameters adequately, and the description adds minimal additional value here.

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 clearly identifies the resource and scope ('cultural story of a colour'), describing exactly what the tool does. It also distinguishes this from siblings like colour_timeline or colour_dna by focusing on the narrative and historical journey. The concrete example reinforces the purpose.

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

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

The description gives clear use cases ('image generation prompts, brand storytelling, and creative briefs') which indicate when to apply the tool. However, it does not explicitly state when not to use it or mention alternative tools for other colour-related analyses, so it falls short of a 5 but provides clear context.

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

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

With readOnlyHint=true already disclosing the non-destructive nature, the description adds meaningful context about what the tool produces: a report with verdict, strategy summary, archive anchor, market readings, usage rules, and copy hooks. This goes beyond the annotation by explaining the actual deliverable, though it doesn't detail any internal processes or edge cases.

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

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

The description is information-dense but well-structured, opening with a clear one-line purpose then organizing inputs, outputs, and examples. It is somewhat long due to the many output fields listed, but every sentence contributes meaningful information. The front-loading of 'Single-call commercial colour strategy report' is effective.

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

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

Given the tool's complexity, the description covers all essential aspects: it explains what the tool does, what inputs are needed, what outputs to expect, and provides representative use cases across industries. An output schema exists, so detailed return-value documentation is unnecessary. The description is sufficiently complete for an agent to decide when and how to invoke this tool.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description's input summary mostly restates the schema structure (brand_context with categories, constraints with avoid/must_work_on), but it adds helpful examples like 'luxury fragrance brand UK/France/Japan' that clarify intended parameter usage. No additional syntax or relationship details are provided 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 opens with 'Single-call commercial colour strategy report'—a specific verb and noun combination that clearly defines the tool's purpose. It then distinguishes itself from sibling tools by enumerating the combined components ('archive grounding, verdict, brand fit, market risk...'), making it obvious this is the comprehensive strategy option rather than a single-purpose tool.

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

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

The descriptor 'Single-call' and the list of combined analyses clearly signal when to use this tool (when a complete strategy report is needed in one call) versus using individual sibling tools like colour_verdict or colour_hooks. It provides clear context and examples of suitable use cases, though it doesn't explicitly state 'use instead of X' or 'don't use when Y'.

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 meaningful behavioral context beyond the readOnlyHint annotation by explaining that the output is a dated sequence of archive entries with primary sources, emphasizing chronological ordering and cultural/historical scope. It does not mention limitations like pagination or failure cases, but with the annotation and output schema, this is sufficient. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the tool's core function. Each sentence earns its place, including the illustrative example that clarifies the concept and shows the historical trace. It is appropriately sized without unnecessary filler.

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

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

Given the tool's low complexity (2 params, 1 required), full schema coverage, existing output schema, and readOnlyHint annotation, the description is complete for an agent to select and invoke the tool correctly. It covers purpose, usage, return format, and an example, leaving no significant 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?

The input schema already provides full descriptions for both parameters (concept and n) with 100% coverage. The description adds an example (indigo) that illustrates the concept parameter, but does not provide additional syntax or semantic details beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: given a concept or colour name, it traces documented appearances chronologically across cultures and centuries, returning dated archive entries with primary sources. This specific verb+resource+scope distinguishes it from sibling tools like colour_story or archive_provenance, and includes a concrete example for the 'indigo' 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 explicitly says 'Use for historical research, provenance chains, and understanding why a colour carries the cultural weight it does.' This provides clear context on when to use the tool, but does not explicitly list alternative tools or exclusions, which would merit a 5.

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

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

Beyond the readOnlyHint annotation, the description discloses important behaviours: the result carries rendered palette downloads to show the customer, the agent must never present archive anchors as recommendations, and the agent should call palette_finalize if it chooses its own palette. This is rich, actionable behavioural guidance.

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

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

Four sentences, each earning its place: what is returned, when to use it, how to display results, and a critical warning plus follow-up action. Slightly long but justifiably dense with operational guidance.

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 read-only tool with an output schema, the description is fully complete. It explains the purpose, the output's practical use, a key pitfall, and the correct downstream action when the agent makes its own palette selection.

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

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

The input schema already provides 100% coverage for the single 'name' parameter. The description reinforces that it must be a 'named archive colour,' which matches the schema example. It adds no major new semantic detail 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 opens with a precise verb and resource: 'For any named archive colour, return historical variants, lighter and darker versions with archive matches, and cultural siblings.' This clearly distinguishes the tool's purpose from many colour-related siblings and states exactly what it produces.

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 usage context: 'Essential for designers exploring around a colour.' It also provides explicit handoff guidance to palette_finalize when the agent forms its own final palette. It does not name other alternatives or exclusions, but the context is sufficiently clear.

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

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

The description discloses valuable behavioral context beyond the readOnlyHint: it explains that the tool is 'Backed by CIEDE2000 archive matching and Claude cultural intelligence' and lists what the output includes ('strengths, risks, avoid-if scenarios, and better alternatives'). This adds a methodological understanding and sets expectations without contradicting the read-only annotation.

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

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

The description is concise and front-loaded: the first sentence states the core purpose, followed by the output verdicts, content included, underlying method, and relevant examples. Every sentence contributes value without redundancy, and the structure is easy to scan.

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

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

For a tool with 5 parameters, an output schema, and a readOnlyHint, the description is remarkably complete. It covers purpose, output values, output contents, methodology, and practical examples, leaving no major gaps. The presence of an output schema means return values need not be described in detail, and the description does not over-explain.

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

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

Schema description coverage is 100%, and the schema already documents each parameter (hex, medium, markets, audience, use_case). The description's examples (e.g., 'luxury hotel brand in Japan') illustrate how parameters combine but do not add new semantic meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Evaluate a hex colour for a specific use case, market, and medium.' It specifies a decisive verb (Evaluate) and the resource (hex colour), and goes beyond by explicitly naming the three possible verdicts (use_with_confidence, use_with_caution, avoid), distinguishing it from sibling tools that assess other aspects like cultural risk or palettes.

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

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

The description conveys when to use the tool through its focus on evaluating a colour for a specific use case, market, and medium, and it provides illustrative examples. However, it does not explicitly mention when not to use it or compare it with alternatives like colour_cultural_risk or palette_verdict, so it lacks explicit exclusions but gives a clear context.

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

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

The readOnlyHint annotation already signals safety, and the description adds substantial behavioral context beyond that: it is a compound tool that returns rendered palettes with PNG/PDF/ASE/JSON/CSS downloads, it warns against presenting archive anchors as the recommended colours, and it instructs the agent to call palette_finalize for any independently chosen palette. This is rich, non-obvious behavioral disclosure that annotations alone would not provide.

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

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

Every sentence earns its place: the compound-tool framing is front-loaded, the replacement chain is explicit, the usage boundary is clear, and the output/presentation warnings are operationally important. Despite its length, there is no filler; each clause carries routing, safety, or workflow information an agent needs.

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 compound tool with 7 parameters and an output schema, the description is complete: it covers what the tool returns, when to use it, when not to, how it differs from siblings, and how to hand off to palette_finalize. The output schema exists, so the absence of a detailed return-value list is not a gap. The readOnlyHint annotation covers the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3; the schema already documents concept, medium, avoid, n_colours, and the include_* flags. The description maps some high-level inputs ('concept, medium, ... constraints') to the schema, but it also mentions 'audience,' which is not an actual input parameter. That minor mismatch prevents extra credit beyond the schema-backed baseline.

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

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

The description uses a specific verb+resource framing: 'One-call compound tool' that 'receive[s] a complete design package' from a concept. It explicitly names the sibling tools it replaces, distinguishing it from query_conceptual, palette_from_concept, colour_story, and others, so an agent can immediately tell this is the aggregator tool rather than any individual step.

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

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

The description states the exact use case ('when an AI agent or user needs a complete, deployable colour direction in a single call') and explicitly says what it is not for ('Not for iterative refinement — use individual tools for that'). It also gives follow-up guidance about calling palette_finalize when the agent chooses its own palette, which is actionable and specific.

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

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

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: copy is grounded in archive provenance, colour names come from the nearest archive match rather than being invented. This goes beyond the annotation by explaining the underlying data source and generation philosophy, providing useful transparency about the tool's behaviour.

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

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

The description is compact and information-dense, covering what it does, inputs, outputs, unique value, examples, and use cases in a single paragraph. Every sentence adds value, and the most important action is stated first. It avoids unnecessary 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?

The description provides a thorough overview of the tool's purpose, inputs, outputs, examples, and applicability. Given the output schema exists and there are no complex side effects or destructive actions, the description is nearly complete. It could mention edge cases like unavailable archive matches, but that is not essential for basic usage.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces parameter purposes through examples (velvet cushion, ceramic vase, linen throw) and mentions the input combination (hex + product type + tone + channel). It does not add significant new semantic detail beyond what the schema already documents, but the examples provide practical context.

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

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

The description clearly states the tool generates complete ecommerce product copy from a hex colour, listing specific inputs and outputs. It distinguishes itself from sibling tools like ecommerce_namer by covering full copy (titles, descriptions, SEO, social) 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?

It gives clear context for use ('Directly useful for Shopify, WooCommerce, and editorial product pages'), implying suitable scenarios. However, it does not explicitly exclude alternatives or state when not to use this tool versus other colour/copy 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 provide readOnlyHint=true, so safety is already declared. The description adds meaningful behavioral context: every name is 'archive-sourced, not invented' and carries a defensible citation. It also states the 40-SKU limit. These go beyond the annotation without contradicting 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 compact and front-loaded with the core action. It covers input, output, and use cases in a few sentences. The redundancy between 'Every name is archive-sourced, not invented' and the following citation sentence is minor but slightly bloats the text.

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

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

For a tool with 5 parameters, an output schema, and read-only annotations, the description is complete: it states the input types, output format, use cases, and quality guarantees. It does not explain the behaviour of max_dE, but the schema describes it, so the gap is acceptable.

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 parameter descriptions are self-sufficient. The description repeats some parameter names (hexes, style, brand, category) and mentions style options already in the schema, but adds no new meaning beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource+constraint: 'Generate archive-grounded colour names for up to 40 product SKUs.' It clearly distinguishes from siblings like colour_namer by emphasizing 'archive-grounded' and the ecommerce context, and it enumerates the exact output fields.

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

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

The description explicitly names target use cases ('Use for paint ranges, candle collections, fashion lines, homeware, cosmetics'), giving clear context. However, it does not state when to avoid this tool or name alternatives such as colour_namer, so it lacks the when-not/exclusion guidance for a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds behavioral context like optional archive matching (analyse, style_context) and the ingest_image dependency flow. However, it doesn't describe the return shape or what happens with conflicting inputs (both image_url and image_id given), and 'ephemeral' image_id isn't elaborated.

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 compact and front-loaded with the core purpose, then branches into usage guidance. No wasted words. Minor deduction for slight redundancy between the ingest_image explanation in prose and the image_id parameter description.

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

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

With 7 params, 0 required, an output schema, and readOnlyHint annotation, the description covers the key decision points: which input to use and when, plus the optional analysis features. Missing behavioral details like behavior on conflicting inputs or error conditions, but the output schema covers return values. Adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds some value by linking image_id to ingest_image and explaining when each input source applies, plus clarifying style_context's purpose (cultural naming coherence). But with full schema coverage, the description correctly leaves heavy lifting to 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 verb+resource ('Extract dominant colours from a photograph') and differentiates method (proprietary k-means++). It distinguishes from siblings: mentions ingest_image for raw uploads and positions it 'before image_brief'.

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

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

Provides explicit when-to-use ('Use this before image_brief when you have an uploaded photograph') and when-not-to ('If you only have a raw uploaded file... call ingest_image first'). Also clearly explains alternative path when no public URL exists.

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

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

Beyond the readOnlyHint annotation, the description discloses the provenance format, names the exact source builds, and explicitly warns that source numbers are not interchangeable and that the response will say so rather than averaging them. This is rich behavioral context that helps the agent anticipate outputs and limitations.

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

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

Although the description is long, every sentence earns its place: main purpose, source inventory, provenance and limitation behavior, example queries, and a critical caveat. It is front-loaded with the purpose and well-structured for a domain-specific query tool.

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

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

Given the rich output schema and annotations, the description covers all necessary selection and invocation context: what question to ask, which sources are involved, what the response will contain, and what it cannot do. No important aspect is missing for an agent to use the tool correctly.

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

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

Input schema covers 100% of parameters, so baseline is 3. The description adds value by enumerating the seven source names and their evidence types, which directly informs the 'sources' parameter and helps shape a good query. It does not comment on mode, max_results, or high_confidence_only, but the schema already describes those.

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 specific verb phrase ('Ask a question about how historical colour authorities actually reasoned') and a clear deliverable ('evidence with provenance rather than a summary'). It differentiates itself from the many sibling colour tools by naming seven specific source builds and the exact use cases, such as checking claims attributed to these authors.

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

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

The description provides explicit 'Use it for questions like...' examples and explains what the evidence can and cannot support. It does not name alternative tools or give explicit when-not-to-use conditions, but the context is clear enough to guide 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?

Beyond the readOnlyHint, it discloses a great deal: grouping_basis and provenance_credit semantics, the provenance-vs-perceptual fallback, the fail-closed ARCHIVE_EVIDENCE_POOL_DEPLETED behavior, that orientation does not affect selection, and a warning that the response is often 60-100KB+ and too large to resend as another call's input. It also clarifies that historical claims are templated only from fields the record states and surface assignment is editorial.

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