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

Adds substantial behavior beyond annotations: OAuth credits vs API-key USD wallet, starting cost, and the quote-then-confirm flow using max_credits or max_usd. This tells the agent how a call can result in charges and how to avoid unintended spend.

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?

Front-loads the purpose, then follows with billing and approval details in two compact sentences. Every sentence carries operational value for invocation.

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?

Covers purpose, billing, and approval well enough to invoke correctly, and the schema documents the image fields. With no output schema, it could have said more about the returned result, but the core invocation context is complete.

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 100%, so the schema already defines all five parameters in detail. The description adds meaningful workflow semantics by linking max_credits to OAuth and currency USD/max_usd to API keys, and by saying to omit approval first for a quote.

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?

States a specific verb and resource ('Remove harsh shadows from a photo') with useful examples ('product shot or a face'). It is clear on its own, but does not explicitly distinguish itself from nearby siblings such as relight_photo or edit_image.

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?

Gives clear usage context with examples and explains the quote/approval workflow before spending credits or USD. It does not state when not to use this tool or name alternatives for shadow correction.

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