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

The description discloses a meaningful side effect beyond the annotations: 'Costs credits from the user's Pixly balance.' It also promises non-destructive behavior by keeping building, trees, and reflections unchanged, and mentions that it matches the light. This gives the agent a clear model of the edit's behavior and side effects.

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 two sentences long, front-loaded with the core operation, and includes only necessary additional context about credit costs. Every sentence earns its place with no filler or redundancy.

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?

The description, combined with the fully documented schema, covers the main usage scenario, input alternatives, and the critical credit-cost side effect. It does not describe return values or job semantics, but no output schema exists and the core invocation details are clear enough for an agent to proceed.

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 100%, with every parameter already documented in the input schema, including the sky enum, sun controls, and the imageUrl/r2Path alternatives. The description itself adds no parameter-specific detail, 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 opens with 'Replace a grey, overcast or blown-out sky in an exterior listing photo with a natural clear blue sky', which names a specific verb, object, and input condition. It also states what will be preserved and that the result matches the photo's light, making the tool's identity unmistakable and naturally distinct from siblings like day_to_night or enhance_photo.

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 clearly states when the tool is appropriate: for grey, overcast, or blown-out skies in exterior listing photos. It does not explicitly name alternatives or exclusion criteria, but the conditions given are specific enough to guide selection.

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