set_icon_rules

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

Without annotations, the description carries the full burden. It explains the interval-based mapping ('each value in [min, max) maps to an icon'), the behavior of glyphs ('each band uses that glyph instead of being colour-keyed'), and the layout option. It also notes 'Verify in Desktop', indicating a post-change verification step. It does not mention whether existing rules are overwritten, but it provides meaningful behavioral detail.

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 a clear purpose sentence, followed by concise explanations of each parameter. It's a single paragraph that is relatively dense but every sentence contributes; no unnecessary fluff. Length is justified by the tool's complexity.

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?

With 9 parameters and no output schema or annotations, the description covers all key aspects: the rule structure, optional glyphs, icon family, and layout. It mentions the target (table/matrix measure column) and adds the 'Verify in Desktop' note. It lacks information about whether the operation replaces or merges existing rules, and doesn't specify return values, but overall it is comprehensive for a formatting 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?

The schema already covers 89% of parameters, but the description enhances understanding by explaining rules format (JSON array of {min, max, color} with interval semantics), providing example glyphs (ArrowDown,ArrowSideways,ArrowUp), and clarifying iconSet and layout values. This adds significant value beyond the schema's terse descriptions.

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 action: 'Apply DISCRETE rule-based ICONS to a measure column in a table/matrix', specifying the resource (measure column) and the distinct approach (discrete rules with [min,max) intervals). It differentiates from siblings like set_color_scale or set_data_bars by focusing on icons.

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 gives clear context ('to a measure column in a table/matrix') and explains the functionality, but it does not explicitly address when to use this tool versus alternatives like set_font_color_rules or set_data_bars. No 'when not to use' guidance or alternative tool references are provided.

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