sharpen

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description need not restate that. It adds useful behavioral context by recommending a checkpoint before running, and by noting 'gentle defaults sigma 2 amount 0.6', which hints at the operation's impact. This goes beyond what annotations provide, but it does not detail side effects such as whether the image is replaced in place or if parameters are clamped.

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 extremely concise, two sentences, with no filler. The core operation is front-loaded, followed by defaults and a checkpoint reminder. Every word contributes value, making it an exemplar of efficient tool documentation.

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 relatively simple operation, the description covers the key points: operation type, stage, defaults, and a safety recommendation. However, it does not mention what the tool applies to (e.g., the active image/window), any return value behavior, or how parameters interact (e.g., whether amount is a multiplier percentage). Given the lack of an output schema and the moderate parameter count, a bit more context would improve completeness.

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 low (20%) with only 'checkpoint' described. The description compensates by giving concrete defaults for sigma (2) and amount (0.6), and by stating the operation is on luminance, clarifying the context for all parameters. It does not explain deringing_dark specifically, but the overall description adds meaningful parameter context beyond 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 clearly states the tool applies an UnsharpMask on the luminance channel with deringing, and specifies it is for the non-linear stage. The verb ('UnsharpMask') and resource (luminance) are specific, and the mention of 'non-linear stage' differentiates it from linear-stage operations like stretch or curves.

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 provides context by specifying 'for the non-linear stage', which helps agents decide when to invoke this tool relative to linear adjustments. It also advises 'Checkpoints first', implying a recommended prerequisite step. However, it does not explicitly name alternative tools to avoid or conditions that would make this tool inappropriate, 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.