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

Goes well past the annotations: WebP recompression at 512px longest side, the same URL written to every id, all-or-nothing write semantics ("If any id is missing, nothing is written"), file retention when a URL is still referenced, and the 1 MB request ceiling with the exact error string. For a destructiveHint=true, non-idempotent mutation, that is precisely the context an agent needs, and it is consistent with the annotations rather than contradicting them.

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-loaded with purpose and the id-targeting model, with constraints following in descending importance. It runs long (roughly eight sentences) and the size-limit discussion takes three of them where two would do, but each sentence carries operational information rather than filler.

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 the risky parts — atomicity, storage retention on replacement, size limits, and org/sheet scoping — which is the right allocation for a mutation tool with no output schema. It falls short only in not explaining sheet_number (relevant when an item appears on multiple sheets) or file_name, and in not hinting at the response shape after a successful upload.

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 0%, so the description carries the burden and largely does: it explains image_base64, item_id, item_ids (max 200), their mutual combinability, and that "Optional column is the photo header name" with visible columns preferred over hidden ones. Two of the six parameters — file_name and sheet_number — are never mentioned, leaving their purpose inferred from the schema alone.

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?

Opens with a specific verb and resource: "Upload one product photo onto one item, or onto variant rows that should share it." That immediately separates it from sibling uploaders such as upload_customer_logo, upload_label_asset, and add_photo_column, since it names photos, items, and variant rows in one clause.

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 operating context: pass image_base64 with item_id for a single item, with item_ids for up to 200 sibling rows, and both are allowed. It also states a negative rule ("A barcode column is not used for images") and "Do not invent image URLs." What's missing is explicit routing versus siblings — nothing says when to use add_photo_column or upload_label_asset instead.

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