SuperCatch

Execute an approved inventory adjustment

supercatch_execute_inventory_adjustment

DestructiveIdempotent

Commit only the exact plan approved in the native web application, once per stable idempotency key. The local receipt and queued follow-up remain separate outcomes. Use the exact owned listing ID and version from SuperCatch's native listing surface. Inventory changes require a separately approved native plan. No pricing, listing identity/content, order, publication or provider-quantity verification changes. A queued follow-up is not provider acceptance. Returns a strict inventory.adjust plan, durable operation receipt or bounded history page. Approval references, credentials and private follow-up details are never returned. Requires OAuth store:inventory:write consent. Requires separate store:inventory:write consent and current EDIT_LISTINGS permission on an approved owned store. One exact listing per plan; plans expire after nine minutes; execution accepts only plan ID, stable idempotency key and the native approval reference when supplied by the approved flow. Commits one approved native stock adjustment and reason-history receipt, then schedules the reviewed marketplace, merchant, webhook and search follow-ups. Queueing does not establish provider acceptance or live channel inventory. Foreign or stale listings, changed reservations or recipients, revoked consent, mismatched plans and reused keys for another intent fail. After an uncertain response, recover the same operation with its original key before any new adjustment.

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": {
      "plan_id": "inventory-plan-id",
      "idempotency_key": "inventory-adjustment-0001"
    },
    "name": "supercatch_execute_inventory_adjustment"
  }
}

Input Schema

Name	Required	Description
`plan_id`	Yes	Persisted exact plan ID returned by the prepare tool; targets and amounts cannot be replaced during execution.
`approval_ref`	No	Optional trusted approval reference for this exact actor, plan and payload. A supplied value is verified; conversational confirmation is not an approval.
`idempotency_key`	Yes	Stable client-generated key for this exact intent. Reuse it after a lost response; a different intent must use a new key.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 5, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the annotations (destructive, idempotent, openWorld), the description discloses plan expiry (nine minutes), the one-listing-per-plan limit, the failure modes (foreign/stale listings, changed reservations, revoked consent, mismatched plans, reused keys for another intent), and the crucial caveat that a queued follow-up is not provider acceptance. It also states the recovery protocol after an uncertain response, which is exactly the kind of behavior an agent needs for a destructive, idempotent mutation.

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

Conciseness3/5

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

The purpose is front-loaded and every major clause carries weight, but the text is dense and repetitive — the consent requirement is stated twice ('Requires OAuth store:inventory:write consent. Requires separate store:inventory:write consent and current EDIT_LISTINGS permission...') and 'queued follow-up is not provider acceptance' appears in near-duplicate form. It reads as a long run-on rather than a structured set of constraints.

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 destructive, idempotent, open-world mutation with three parameters, the description covers authority (consent + EDIT_LISTINGS), plan freshness/expiry, failure conditions, idempotency recovery, and the boundary between commit and downstream propagation. An output schema exists, so the brief return-value sentence is sufficient rather than burdensome.

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 100%, so the baseline is 3; the description adds real meaning by constraining execution to 'only plan ID, stable idempotency key and the native approval reference when supplied by the approved flow' and by clarifying that a queued follow-up does not imply acceptance. It also reinforces the reuse-the-original-key semantics for idempotency_key, though it doesn't add format or validation detail beyond what the schema already provides.

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?

The opening sentence names a specific verb and resource ('Commit only the exact plan approved in the native web application, once per stable idempotency key') and immediately scopes it against the sibling prepare step by insisting the plan must already exist. An agent can tell this apart from supercatch_prepare_inventory_adjustment without opening either schema.

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?

It gives strong when-to-use/when-not guidance: 'Use the exact owned listing ID and version from SuperCatch's native listing surface', 'Inventory changes require a separately approved native plan', and an explicit exclusion list ('No pricing, listing identity/content, order, publication...'). It stops just short of naming the alternative tools (prepare_inventory_adjustment, get_inventory_plan) outright, so routing is implied via 'prepare tool' rather than explicit.

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?