adjust_image

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

With no annotations, the description carries the full behavioral burden and does so well. It discloses that out-of-range values are rejected rather than clamped, that the operation runs in linear light and therefore has a stronger effect than in GIMP 2.x, and that values past +/-0.1 visibly change the image. This goes well beyond a generic 'adjusts brightness and contrast.'

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 front-loaded with the core purpose and then adds only high-value behavioral and practical details. Every sentence earns its place: the range/rejection rule, the relationship to enhance_image, the linear-light warning, and the guidance to keep adjustments small.

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 six-parameter tool with no annotations and 0% schema coverage, the description is nearly complete: it explains the main operation, the key parameters, edge-case behavior, and how values behave differently in GIMP 3. It misses only the optional backend and quality semantics, which keeps it from a perfect score.

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 description coverage is 0%, so the description must compensate. It provides rich semantics for brightness and contrast (range, rejection behavior, practical limits), but says nothing about backend or quality, leaving the quality default of 0.92 unexplained. The required input_path and output_path are self-evident from their names, so the gap is mainly in the optional parameters.

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 'Brightness/contrast touch-up,' a specific verb and resource that immediately identifies the tool's function. It also references enhance_image, providing a sibling distinction even though the exact selection criteria are not spelled out.

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 gives useful operational guidance about value ranges and suggests keeping adjustments small, but it does not explicitly state when to choose adjust_image over enhance_image or other siblings. The mention that both wrap the same GIMP call is informative but stops short of routeing the agent to the right tool in a specific scenario.

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