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

Beyond the readOnlyHint annotation, the description discloses that the call is deterministic and has no LLM cost, which sets cost and behaviour expectations. It also states that the result already carries the rendered palette and download files (PNG, PDF, ASE, JSON, CSS) and instructs the agent to show them to the customer. The guardrail about archive anchors and the palette_finalize handoff add meaningful operational context that annotations do not provide.

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 front-loads the core purpose and output list in the first sentence, then layers cost/determinism, embedded deliverables, presentation instructions, and a cross-tool handoff. Each sentence earns its place: the determinism note, the 'show them to the customer' directive, and the palette_finalize routing all affect agent behavior. It is long but appropriately so for a complex aggregate 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?

Given the tool's complexity—5 parameters, output schema, many siblings—the description is operationally complete. It explains what the tool returns, that it is deterministic, that downloads are embedded, how to present results, and what to do if the agent selects its own palette. Parameter details are already in the schema, and return structure is covered by the output schema, so nothing critical 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?

The input schema covers all 5 parameters with 100% schema description coverage, so the baseline is 3. The description does not add extra meaning for market, medium, palette, use_case, or brand_category. Since the schema already documents these parameters well, the description does not need to compensate and no deduction is warranted.

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 opens with 'Complete brand colour system in one call' and then enumerates concrete deliverables such as colour roles, light/dark role maps, typography guidance, usage rules, design tokens, and citation cards. This gives the agent a specific verb, resource, and scope. It also references palette_finalize as a distinct follow-up, which helps separate this aggregate tool from siblings.

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 clearly indicates when to use the tool—when a complete brand colour system is needed in one call—and gives an explicit alternative: if the agent chooses its own final palette, it should call palette_finalize once with those colours. It also provides concrete behavioural guidance such as 'Never present the archive anchors... as the colours you are recommending.' It stops short of listing exclusions for narrower palette tasks, but the routing is clear.

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