restore_star_color

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It fully delivers: it states the in-place mutation, the exact per-channel formula, linear weighting behavior, 64-bit PixelMath execution, truncation to [0,1], and the reporting of median/max before and after. This gives an agent a complete behavioral model beyond the schema.

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 dense but every clause earns its place: purpose, formula, weighting, numeric precision, and reporting. It is front-loaded with the core action and then clarifies mechanics, making it efficient without filler.

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 no output schema and no annotations, the description is remarkably complete. It covers inputs, the algorithmic transformation, edge-case behavior, execution mode, and observable output (before/after stats). An agent has enough information to invoke the tool correctly and interpret its side effects.

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?

Even though schema coverage is 100%, the description adds significant semantic depth by tying parameters directly into the formula: max_value as the upper cap, restore_start and restore_end as the linear weighting range, and target_id/pre_star_id as the target and reference. It also explains edge behavior, such as the max(Lr, 0.001) denominator, which is not present in the schema.

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 states a specific verb ('Restore'), the resource ('the colour ratios of a reference view'), and the precise scope ('in the bright areas of a target'), while also noting it is in-place and preserves luminance. This clearly distinguishes it from generic tools like run_pixelmath and from other star-related tools by specifying the exact operation and domain.

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 clearly implies when to use the tool: when you need to restore reference color ratios in bright areas while keeping the target's luminance. It does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5, but the context is unambiguous enough for selection among the large sibling list.

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