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

With readOnlyHint=true already disclosing the non-destructive nature, the description adds meaningful context about what the tool produces: a report with verdict, strategy summary, archive anchor, market readings, usage rules, and copy hooks. This goes beyond the annotation by explaining the actual deliverable, though it doesn't detail any internal processes or edge cases.

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 information-dense but well-structured, opening with a clear one-line purpose then organizing inputs, outputs, and examples. It is somewhat long due to the many output fields listed, but every sentence contributes meaningful information. The front-loading of 'Single-call commercial colour strategy report' is effective.

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, the description covers all essential aspects: it explains what the tool does, what inputs are needed, what outputs to expect, and provides representative use cases across industries. An output schema exists, so detailed return-value documentation is unnecessary. The description is sufficiently complete for an agent to decide when and how to invoke this 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 description coverage is 100%, so the schema fully documents each parameter. The description's input summary mostly restates the schema structure (brand_context with categories, constraints with avoid/must_work_on), but it adds helpful examples like 'luxury fragrance brand UK/France/Japan' that clarify intended parameter usage. No additional syntax or relationship details are provided beyond 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 opens with 'Single-call commercial colour strategy report'—a specific verb and noun combination that clearly defines the tool's purpose. It then distinguishes itself from sibling tools by enumerating the combined components ('archive grounding, verdict, brand fit, market risk...'), making it obvious this is the comprehensive strategy option rather than a single-purpose tool.

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 descriptor 'Single-call' and the list of combined analyses clearly signal when to use this tool (when a complete strategy report is needed in one call) versus using individual sibling tools like colour_verdict or colour_hooks. It provides clear context and examples of suitable use cases, though it doesn't explicitly state 'use instead of X' or 'don't use when Y'.

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