util_cbag

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

Annotations already declare idempotentHint=true, destructiveHint=false, openWorldHint=false and readOnlyHint=false, which tells the agent this mutates the scene non-destructively — the description adds only the carbon color, which is already implied by the name. It does not say that existing colors of non-carbon atoms are overwritten by the element scheme, whether the change is undoable, or what the output schema returns after the recolor. For a state-mutating tool the description carries little of the extra burden.

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?

It is short and front-loaded, which fits a small utility tool, but the parenthetical repeats the tool name's own abbreviation and much of the first clause. Two of the five words are redundant expansion rather than information.

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?

The tool is a simple one-parameter recolor utility with an output schema and full annotation coverage, so little elaboration is required. The remaining gap — what colors non-carbon atoms receive and how the result differs from the other carbon-color variants — is modest but real.

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?

Only one optional parameter (selection) exists and schema description coverage is 100%, with the schema itself stating 'What to recolour. Defaults to everything.' The description adds no syntax or scoping detail beyond that, but the baseline of 3 applies when the schema does the heavy lifting.

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 does state a verb ('Colors') and a scheme ('by atom') plus a specific carbon color ('green'), so an agent can roughly infer the effect and tell it apart from util_cbam/util_cbay by carbon color. However, 'by atom' largely restates the 'cba' mnemonic in the tool name, and the parenthetical '(Color By Atom, Green)' is simply an expansion of the name rather than an explanation of what non-carbon atoms get. It lands at vague-but-usable rather than a crisp statement of behavior.

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?

There is no guidance on when to use util_cbag versus the many siblings (util_cbam, util_cbay, util_cbac, util_cbaw, util_color_by_element, util_rainbow, or even the generic color command). The agent must deduce from the one-word 'Green' suffix which of the near-identical carbon-coloring variants to pick. No prerequisites, no exclusions, no mention of alternatives.

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