color_splash

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

With no annotations provided, the description carries the full burden, and it excels. It discloses key behavioral traits: overrides are applied 'in the ACTIVE view only,' 'other views are untouched,' 'overrides persist in the view until clear_colors is called,' and the return value includes 'the colour assigned to each distinct value, plus counts.' It also explains the gradient behavior and text-value limitations.

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 well-structured: an introductory purpose sentence, a use-case sentence, behavior and return-value sentences, a prerequisite instruction, and a clear Args list. Every sentence adds useful information, and the front-loaded intro immediately communicates the tool's function.

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 4 parameters, no annotations, and no output schema, the description is remarkably complete. It explains scope (active view), longevity (until clear_colors), return values (color and counts), parameter examples, and gradient/custom-color behavior. The only minor omission is error handling for invalid categories, but this is not essential given the explicit prerequisite.

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 0%, so the description must fully explain each parameter, and it does. Each arg includes an example and additional guidance (e.g., use_gradient 'Suits numeric parameters; poor for text values' and custom_colors as 'Optional hex colours to use in order'). This goes well beyond the schema's minimal names and types.

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 a specific verb+resource: 'Colour-code elements of a category by the value of one parameter.' It clearly states what the tool does and includes examples like 'phasing, fire rating, room department, wall type distribution' that distinguish it from sibling tools such as list_category_parameters or clear_colors.

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 usage context: it is 'the fastest way to visually audit a model,' applies only to the active view, and explicitly instructs to 'Use list_category_parameters first to get a valid parameter_name.' It also mentions that overrides persist until clear_colors is called, which points to the relevant alternative for undo. It does not explicitly state when not to use this tool versus other coloring or modification tools, so it falls short of a 5.

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