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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description instead adds the things annotations cannot, notably the exact OKLCH hue bands (warm 350-115, cool 180-285, neutral chroma <0.03), the 60-30-10 tolerance windows (50-70/20-40/5-20), and the explicit degradation behaviour when shares are missing. It does not mention what happens with an unparseable colour string, which keeps it from a 5.

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

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

A single dense block that is correctly front-loaded: purpose, then input format with a concrete example, then outputs, then conventions. It is long but nearly every clause carries information; the closing source citations are the only part that does not help an agent invoke the tool.

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

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

With no output schema, the description must enumerate return values, and it does so thoroughly (shares, weighted index, chroma spread, lightness range, contrast, named colours). Combined with fully documented input syntax and stated edge-case behaviour, an agent has everything needed to call and interpret this closed-world read 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% for the single parameter, so the baseline would be 3, but the description adds meaning the schema lacks: the two-to-sixty colour count constraint, the accepted colour syntaxes (hex, rgb(), hsl(), CSS names), and the trailing-share shorthand. It stops short of explaining how shares are normalised when they do not sum to 100.

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?

"Read a palette's balance" gives a specific verb and resource, and the enumerated outputs (warm/cool/neutral share, chroma-weighted index, dominant/accent/neutral colors) make clear this is a temperature-analysis tool rather than a harmony or contrast checker. It never names a sibling such as palette_harmony or chart_colour_check, so differentiation is by inference from the described return values rather than by explicit routing.

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 is implied by the input-shape rules: with shares it reports a 60-30-10 read, without shares it declares the split unreadable. That is useful input guidance, but the description never states when to reach for this tool instead of the many colour siblings, nor any prerequisite or exclusion.

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