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

Consistent with readOnlyHint=true and adds substantial context the annotation cannot carry: deterministic execution, no LLM cost, the scored dimensions, the prioritised fix list, and the fact that the result already bundles a rendered palette with PNG, PDF, ASE, JSON and CSS downloads for customer presentation. It also pre-empts a likely misreading by clarifying that archive anchor colours are evidence, not recommendations.

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 purpose, then scoring dimensions, then output, then workflow — a sensible order with no filler. The closing sentences on archive evidence and palette_finalize are useful but make the block longer than strictly needed for an audit tool; they read as downstream workflow guidance folded into the audit 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?

For a tool that already has an output schema and full annotation coverage, the description supplies everything else an agent needs: what is scored, what comes back, that it is deterministic and cheap, that artefacts are downloadable, and how the result chains into palette_finalize. The one caveat is that those artefacts and the finalize handoff would ideally live in the sibling tool's description, but coverage here is complete for decision-making.

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 market, medium, use_case and palette are already documented in the schema, which sets the baseline at 3. The description adds no syntax, defaults, or constraint detail beyond that (e.g. hex format, how market/medium shift the scoring), so it earns no more than 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?

States a specific verb and resource ('Full palette quality audit') and enumerates the graded dimensions: accessibility, cultural risk, tonal balance, colour diversity, archive naming strength. It also states the return shape (0-100 score, grade, prioritised fix list), so an agent can distinguish it from sibling scoring tools like palette_verdict or palette_analyse 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?

Gives a concrete trigger condition ('Enterprise quality gate -- use before shipping any palette') and routes the follow-on step explicitly to palette_finalize with its calling convention (once, with the exact chosen colours). It does not state when to prefer this over adjacent siblings such as palette_verdict, palette_strict, or palette_analyse, so the exclusion side of the guidance is incomplete.

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