SuperCatch

Prepare a saved photo draft update

supercatch_prepare_listing_draft

Freeze one exact owned photo draft, an explicit existing catalog card, optional draft seller notes and either a full saved-photo permutation or one explicit quarter/half-turn rotation. Photo edits require additional image-write consent and preserve original archives. Rotation renders once from the stable base into new verified display artifacts; restoring the base, cropping, adding and deleting photos are unavailable. Use the native upload link for new photos before preparing. Save front and back photos through SuperCatch's authenticated /store/listings/new flow, inspect that owned DRAFT and select an exact existing catalog card. Prepare and execute a single frozen update to that same draft. No arbitrary photo URLs, chat-attachment ingestion, new catalog rows, grading or authenticity verification, price, inventory or publication changes. A strict canonical plan or durable operation envelope with exact listing, catalog and version references. Private photo and card-data snapshots stay server-side. Requires OAuth store:listings:drafts:write consent. Requires separate store:listings:drafts:write consent and current EDIT_LISTINGS permission on an approved owned store. Optional photo order additionally requires store:listings:drafts:images:write; existing catalog/copy grants never acquire photo-write authority. Existing read and price grants do not authorize drafts. One draft per plan; nine-minute expiry; execute accepts only the plan and stable idempotency key. Preparation adds an expiring plan. Execution replaces the existing draft's catalog association and persisted card-data snapshot, with model edits limited to seller notes; an optional frozen photo permutation or explicit photo rotation also replaces draft display state. Photo changes require additional photo-write consent. Rotation retains its stable base and original archives and creates a complete verified artifact set with a durable receipt. Existing price is preserved, the listing remains DRAFT, and there are no marketplace writes. Missing or foreign drafts, unowned preserved originals, incomplete photo pairs, stale versions, changed catalogs and revoked authority fail. After a lost response, inspect the same operation or find it by its original key; unknown outcomes must not be retried as new intent.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "catalog_id": "selected-catalog-id",
      "catalog_type": "SPORTS_CARD",
      "source_draft_id": "owned-draft-id",
      "expected_version": "2026-11-04T16:00:00Z"
    },
    "name": "supercatch_prepare_listing_draft"
  }
}

Input Schema

Name	Required	Description
`catalog_id`	Yes	Exact existing catalog row ID selected in the native listing flow. This cannot create a catalog row.
`copy_edits`	No	Optional explicit copy edits for this saved draft only; no price, inventory, condition, grade or identity replacement fields are accepted.
`image_order`	No	Requires separate store:listings:drafts:images:write consent alongside draft-write consent. Optional exact permutation of saved photo positions: each output position names its previous zero-based index. Must include every saved photo exactly once. Moves existing photos and original pointers; cannot crop, rotate, add or delete photos.
`catalog_type`	Yes	Exact native catalog family of the selected existing card; mismatched families are refused.
`photo_rotation`	No	Requires separate photo-write consent. Rotate one saved photo by an explicit clockwise quarter or half turn (negative means counterclockwise). Cannot be combined with image_order; no caller URLs, crop, replacement or deletion.
`source_draft_id`	Yes	Exact existing DRAFT listing ID owned by this store.
`expected_version`	Yes	Exact updated_at version returned by the native draft surface; stale drafts cannot be updated.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 5, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations only declare readOnly=false, idempotent=false, destructive=false, openWorld=false; the description goes far beyond them with consent scopes, a nine-minute plan expiry, one-draft-per-plan scope, idempotency-key semantics, exactly what is replaced (catalog association, persisted card-data snapshot, display state), what is preserved (original archives, price, DRAFT status), and enumerated failure conditions (foreign drafts, stale versions, revoked authority). This is exactly the behavioral context an agent needs before invoking a state-changing plan tool. No contradiction with the annotations: replacement of draft state is disclosed consistently with destructiveHint=false since originals are archived, not destroyed.

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

Conciseness2/5

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

The description is an undifferentiated wall of text with genuine repetition — the draft-write consent requirement is stated twice in adjacent sentences, and photo-write consent is re-stated three separate times ("Photo edits require additional image-write consent", "Optional photo order additionally requires...", "Photo changes require additional photo-write consent"). The key exclusions and consent requirements are not front-loaded or grouped, so an agent must re-read to extract the contract.

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?

Given seven parameters, nested objects, an output schema and non-trivial auth, the description covers everything material: prerequisites, consent scopes, plan lifetime, mutual exclusivity of image_order and photo_rotation, exact write effects, preserved state, and failure/retry behavior. Return values are correctly left to the output schema. Nothing an agent needs to call this correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents every parameter including the enum, the permutation semantics and the rotation degrees. The description adds only marginal meaning beyond it: that photo order requires images:write consent alongside draft-write, and that image_order must be a full permutation and cannot combine with rotation. Baseline 3 applies when the schema carries the parameter burden.

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

Purpose4/5

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

The opening sentence names a specific verb and resource: freeze one exact owned photo draft plus an explicit existing catalog card, with optional notes or a photo permutation/rotation. It clearly delineates this as the preparation half of a two-step flow ("Preparation adds an expiring plan. Execution replaces..."), which implicitly separates it from supercatch_execute_listing_draft. It falls short of 5 because the core purpose is buried inside a very long compound sentence and no sibling is named outright.

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

Usage Guidelines4/5

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

Gives real when-to guidance: photos must first be saved through the authenticated /store/listings/new flow, the native upload link is the path for new photos, and this tool then prepares and executes against that same draft. It also gives strong failure/retry guidance ("After a lost response, inspect the same operation or find it by its original key; unknown outcomes must not be retried as new intent"). No explicit named alternative (e.g. supercatch_prepare_listing_submission or supercatch_get_listing_draft_readiness) is cited, so it stops short of 5.

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

All SuperCatch 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?