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

Annotations declare readOnlyHint=true, which aligns with the extraction (read-only) nature of the tool. The description adds useful behavioral context beyond this: the algorithm used (k-means++), the dual input path requirement (URL vs ID), and the fact that style_context optionally matches against an archive for cultural naming. It doesn't describe rate limits or error behaviour, but for a read-only extraction tool this is adequate.

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 zero waste. It front-loads the core purpose and algorithm, covers the critical input logic (URL vs ID, ingest flow), notes functionality (hex weights, cultural matching), and ends with usage positioning. Every sentence contributes meaningful information.

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

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

Given the output schema exists, the description doesn't need to explain return values. It adequately covers the dual input modes, the prerequisite ingest_image flow, and the optional analysis feature. The only minor gap is that it doesn't explicitly note grey_card_hex usage context (white balance calibration), but the schema covers that. For a 7-parameter tool with full schema coverage and an output schema, this is well-rounded.

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

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

Schema coverage is 100%, so all 7 parameters are documented in the schema. The description adds value by explaining the relationship between image_url/image_id (mutually exclusive input options) and clarifies the ingest_image prerequisite flow. However, the description doesn't add much beyond the schema for individual parameters like k, grey_card_hex, or style_context — those are already well-named and documented in the schema itself.

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 extracts dominant colours from a photograph using a named algorithm (k-means++), and specifies the exact inputs (image_url or image_id) and outputs (hex values with proportional weights, optional cultural naming). It also distinguishes itself from siblings by explicitly positioning it before image_brief and referencing ingest_image for upload flow.

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

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

The description provides explicit guidance: requires either public image_url OR image_id; if the user has a raw file without a public URL, call ingest_image first. It also states when to use this tool ('Use this before image_brief when you have an uploaded photograph') and mentions the optional style_context/analyse flow for archive matching. This is excellent when-to-use coverage.

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