util_cbay

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

With no annotations provided, the description should disclose behavioral traits like whether existing colors are replaced, how the selection parameter affects coloring, or what state changes occur. It only states the action ('Colors by atom, yellow carbons') without such detail, though it does not contradict any annotations.

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 very short and front-loaded, but the parenthetical '(Color By Atom, Yellow)' is redundant with the main phrase and wastes words. It is concise but under-specified, balancing brevity with a lack of useful elaboration.

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 one-parameter tool with full schema coverage and an output schema, the description is minimally functional but leaves key context unanswered: how selection interacts with coloring, what 'by atom' means in practice, and when to use this variant over siblings. The agent would need to infer or guess to invoke it correctly.

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 input schema already provides 100% coverage for the single 'selection' parameter, including a default and description ('What to recolour. Defaults to everything.'). The tool description adds no further parameter semantics, so the baseline score of 3 is appropriate.

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 a specific coloring operation ('Colors by atom') with a specific target ('yellow carbons'), which distinguishes it from sibling color utilities like util_cbc. However, it is terse and does not elaborate on the 'by atom' convention beyond the short phrase.

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 this tool versus alternatives such as util_cbc, util_cbag, or other color utilities. No exclusions, prerequisites, or typical use cases are mentioned, making it hard for an agent to choose it confidently.

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