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.