set_color_scale

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: data min/max is auto-computed, centerColor enables a diverging scale, and objectName/propertyName presets target specific visual elements. It does not explicitly mention reversibility, permissions, or potential side effects, but for a formatting tool these are generally inferred. The added detail goes well beyond a bare description.

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 reasonably concise despite carrying substantial detail. It front-loads the core purpose, then supplies examples and presets in a structured way. The phrase 'the signature enterprise feature' is slightly promotional but does not harm clarity. Overall, each sentence contributes useful information with minimal fluff.

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 14 parameters and no output schema, the description is remarkably complete. It covers the core action, provides example use cases, lists parameter presets, explains auto-computed min/max, describes diverging scales, and points to an alternative. It also notes when metadata should be omitted. This matches the completeness expected for a complex 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 79%, so the schema already explains most parameters. The description adds extra meaning for ambiguous parameters: it explains valid objectName/propertyName combos (e.g., 'dataPoint/fill', 'values/backColor'), notes that metadata is for table/matrix columns and should be omitted for charts, and clarifies the role of centerColor for diverging scales. This exceeds the baseline for high-coverage schemas.

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's function: 'Apply a GRADIENT colour scale to a visual property driven by a measure.' It immediately distinguishes itself from set_conditional_formatting by noting that tool is for discrete colour bands, and it provides concrete examples of visual properties (dataPoint/fill, values/backColor, values/fontColor). This is a specific verb+resource+scope that differentiates it 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 provides explicit when-to-use guidance: it gives examples of when to use this tool (colouring a table value's background, chart bars, etc.) and explicitly points to an alternative for a different scenario: 'For DISCRETE colour bands by value range instead, use set_conditional_formatting.' This satisfies the 'when/when-not/alternatives' requirement at a high level.

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