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

Annotations only declare readOnlyHint, but the description adds substantial behavioral detail: outputs include archive grounding, change rationale, rendered palette, and downloadable assets. It also discloses an important anti-pattern: never present archive anchors as recommended colors. This goes well beyond the structured 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 core purpose and stays relevant throughout. The examples of feedback and the explicit caveats about not presenting archive anchors and calling palette_finalize are valuable enough to justify the length. Slight redundancy between 'using natural language feedback' in sentence one and 'Submit ... feedback' in sentence two, but no wasted sentences.

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 six parameters and an output schema, the description covers what an agent needs: it explains the inputs, the output format, the deliverables, and the downstream workflow. It also provides guardrails that prevent incorrect customer-facing behavior. The output schema handles detailed return structure, so no additional return documentation is required.

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 meaningful semantic context for the two core parameters, palette and feedback, with concrete examples of acceptable feedback phrasing. It also clarifies that the result is a complete deliverable including downloads, which indirectly explains the value of n_results and use_case. The remaining parameters are adequately documented 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 uses a specific verb-resource pair, 'Refine an existing palette', which clearly distinguishes it from generating a new palette or finalizing one. It also explicitly names the follow-up tool, palette_finalize, reinforcing the tool's 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 states a clear use context: submit a current palette plus natural language feedback to get a refined palette, with concrete feedback examples. It provides strong routing guidance by instructing when to call palette_finalize instead of presenting intermediate results. It does not explicitly enumerate exclusion cases versus generate/specify tools, but the context is clear enough.

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