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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds material traits the structured fields cannot express: credits are spent only after owner approval, image-edit permission is a one-tap account-level grant, results land in the Soclo Library, a pending result reattaches on identical inputs, and an exact replay returns the original picture with no second charge. The recovery-vs-replacement rule and output field names (libraryAssetId, resultUrl) round out the behavior disclosure.

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?

Purpose and the quote-first rule are front-loaded, and most sentences carry operational weight. It is dense at roughly ten sentences and repeats clientRequestId guidance already present in the schema, which costs a point but not the structure.

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 credit-spending, destructive, no-output-schema tool with 10 parameters, it covers cost approval, idempotent replay, recovery, permissions, result destination, and the non-publishing boundary. Nothing an agent needs to call it safely and correctly is missing.

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 baseline is 3, but the description adds workflow meaning beyond the schema: expectedCredits/pricingVersion/ownerApprovedPrice must come from the approved quote with zero allowed only when the account quote permits, and imageUrls must keep the original order from the reference-prepare step. It also instructs generating clientRequestId before calling, clarifying sequencing rather than format.

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 (apply the owner's edit prompt to reviewed photos) and explicitly bounds the outcome with 'This tool does not publish.' It is cleanly separable from soclo_image_generate and from the quote sibling, so an agent can pick it without opening the schema.

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 the full when-to-use chain: quote first via soclo_image_photo_edit_quote, source locators from soclo_photo_reference_prepare or soclo_brand_photo_reference, and the failure path via soclo_image_recover with the original clientRequestId. It also states exclusions ('never start a replacement purchase') and the approval precondition, leaving no routing inference to the agent.

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