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

Goes well beyond the annotations: no storage is allocated until upload, idempotency keys must be stable and reused with identical bytes on retry, and a GET /api/uploads/{key} exists for lost responses. Supported MIME types, octet-stream fallback, and conversion of unsupported encodings are disclosed. It does not clarify the relationship between 'Create Upload' and readOnlyHint=true, leaving the mutation profile slightly ambiguous, which keeps it off a 5.

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 core action, but then accumulates a dense run-on of SDK URL, format list, MIME fallback, encoding conversion, and payment-retry caveats in a single block. Each fact is useful to someone, yet the density makes it hard to scan and the SDK link sits awkwardly mid-paragraph.

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?

Given an output schema exists, the description doesn't need to explain return values and instead covers the operational essentials: endpoint/header retrieval, per-image uploads, idempotent recovery, and accepted formats. Only the guestToken/auth relationship and the readOnly-vs-upload semantics are left under-explained.

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 only 33%, so the description must compensate. It adds real meaning for productId (source it from list_products) and for crop (use that product's artwork specs, not a universal 4x6), but guestToken and the crop sub-fields x/y/fit/orientation are never mentioned. Partial but meaningful compensation.

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 first sentence names the concrete resource: an authenticated binary upload endpoint plus product/crop headers, and later sentences make clear this is the per-image upload path. It routes the agent to list_products for the productId, which distinguishes it from the catalog siblings. It is slightly muddied by mixing 'get endpoint' with 'upload each image', so the agent must infer that the tool itself returns the endpoint rather than carrying bytes.

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?

Explicit when-to-use rules: pass productId from list_products for every image, upload each required image separately, and keep returned IDs in slot order. It also draws a hard boundary against payment flows ('never retry payment as an upload recovery step'), which is exactly the kind of sibling confusion an agent would otherwise hit.

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