shopify_upload_image

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

Annotations already indicate a destructive, non-read-only mutation. The description adds useful behavioral context beyond those flags: it waits for async processing and returns a CDN URL, and it supports local files or HTTPS URLs. It doesn't fully describe side effects, but it meaningfully supplements the annotation profile.

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?

A single, front-loaded sentence conveys the action, input forms, processing behavior, and output. Every phrase is informative and there is no filler or redundant restatement of the tool name.

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 six-parameter mutation with no output schema, the description is too thin. It lacks guidance on choosing between imageFile and sourceUrl, the required confirm confirmation flow, and the actual response shape beyond 'CDN URL'. An agent would need to inspect the schema and sibling context to call this correctly and safely.

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 17%, and the description does not compensate for the remaining five undocumented parameters. It loosely maps 'local image' to imageFile and 'HTTPS source' to sourceUrl, and implies the result is a CDN URL, but store, confirm, filename, and alt are not explained in the description. The confirm-gating behavior is critical and only appears in the schema.

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 states a specific action ('Upload'), a resource ('local image or HTTPS source to Shopify'), and a concrete outcome ('return a CDN URL'). It also adds the behavioral detail that it waits for processing. This makes the tool's purpose unmistakable and clearly distinguishes it from retrieval siblings like shopify_get_uploaded_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?

The description implies the tool is for uploading images and mentions both local and HTTPS sources, but it never states when to prefer this over shopify_get_uploaded_image or other image-related tools. There are no explicit exclusions or alternative routing instructions.

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