ApparelHub

generate_listing_image

Generate listing photography for an existing product — an on-model shot, a detail crop, a flat lay, or the product in a real setting.

HOW IT WORKS: this EDITS the product's own rendered mockup. It is not text-to-image, and that is the point — the photo shows the actual colourway and the actual printed design, so it depicts the product a shopper will receive.

⚠️ A PRODUCT WITH NO MOCKUP IS REFUSED, not silently generated from scratch. A from-scratch product photo invents a product that does not exist and publishes it as photography of one that does — a listing-takedown and chargeback risk, not merely a quality problem. On product_has_no_mockup, render a mockup preview first (ship_product / create_product do this) and call again. Raw print artwork does not count as a mockup.

guidance is EXTRA wording folded in on top of the chosen preset — it does NOT replace it, and it cannot override the constraint that keeps the garment, colour and artwork unchanged. Use it for setting or mood ("outdoors at golden hour"), not to restate the product.

COST: this spends an image generation from the account's quota, like any other. Four styles across thirty products is 120 generations — more than some plans allow in total. Check the plan before looping over a catalogue.

By default the image is generated and RETURNED, not attached: putting a machine-made photo on a live storefront is a separate decision from making one. Pass attach: true to append it to the gallery — appended, so existing images are kept, unlike set_product_images which replaces the whole gallery.

[#b24313]

Input Schema

TableJSON Schema

Name	Required	Description
`style`	Yes	Which preset to use. `on_model` = worn by a person; `detail` = close crop showing fabric and print texture; `flat_lay` = styled flat, shot from above; `lifestyle` = the product in a real setting. The preset supplies the prompt.
`attach`	No	Append the result to the product's listing gallery (default false). Existing images are kept. Leave false to review the image before it reaches a storefront.
`guidance`	No	Optional extra direction layered on top of the preset (setting, mood, lighting). Truncated at 500 characters by the platform.
`workspace`	No	Workspace uuid (agency accounts).
`product_uuid`	Yes	The product to photograph. Its existing mockup is what gets edited.
`set_as_cover`	No	When attaching, also make it the listing cover. Ignored unless `attach` is true.
`source_image_url`	No	Which of the product's existing listing images to edit. Must be one of them and must not be raw print artwork. Defaults to the product's best mockup — usually leave unset.

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only carry openWorldHint, so the description must do the heavy lifting — and it does: it discloses the refusal-on-missing-mockup behavior, that it edits the existing mockup rather than inventing a product, that generation spends account quota, and that the result is returned but not attached by default.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the what, then labeled HOW IT WORKS, a bolded warning, COST, and default-behavior sections. Efficient for the amount of risk it must convey, though the cost paragraph and warning overlap slightly and the trailing marker token is noise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutating/generating tool with no output schema, the description covers refusal conditions, cost, default-vs-attach semantics, and sibling contrast. An agent has everything needed to call it correctly and safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description still adds meaning: `guidance` is additive and cannot override product fidelity, `attach` appends rather than replaces, and `source_image_url` must be an existing listing image and defaults to the best mockup. This goes beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — generating listing photography for an existing product — and enumerates the four styles (on-model, detail, flat lay, lifestyle). It crucially distinguishes itself from text-to-image and from from-scratch generation, which an agent cannot infer from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-not (no mockup → refused, use ship_product/create_product first), names the sibling it contrasts with (set_product_images replaces the gallery, this appends), and explains how to use `guidance` correctly. Even includes a cost/looping caution for catalogue-wide use.

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

All ApparelHub tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?