gradient_correction

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

Annotations already mark this as destructive, and the description reinforces this with 'Checkpoints first.' It also discloses the dry_run behavior (reports DBE sample layout) and the expected post-invocation action (look at the preview). This is useful behavioral context beyond the 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?

Three compact sentences carry the core action, method selection, and workflow guidance without repetition. The method parenthetical is dense but every clause earns its place, and the most critical safety instruction appears early.

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 destructive 12-parameter tool with no output schema, the description supplies method routing, workflow state, and safety behavior. Minor gaps remain around the exact meaning of subtract versus divide correction and the role of the required id, but an agent has enough context to invoke and validate the operation 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?

Schema coverage is 67%, so the description must add value. It clarifies the method enum values, their defaults and preferences, explains what dry_run reports, and introduces checkpoint behavior. It does not explain the correction subtract/divide enum, which would help the agent choose correctly, but the covered parameters are substantially enriched.

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 and resource: 'Remove light-pollution gradients on a LINEAR image.' It meaningfully distinguishes the tool from sibling operations like background_neutralize and color_calibrate by focusing on spatial gradients rather than color casts, and it differentiates internal methods (DBE, GradientCorrection, ABE).

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?

It gives explicit selection guidance: DBE is the user's preferred method, GradientCorrection is the default when DBE is not requested, and ABE is an alternative. It also tells the agent to checkpoint first and inspect the preview afterwards. It does not, however, state when to avoid this tool in favor of a sibling like background_neutralize.

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