Skip to main content
Glama
Sign In

SuperCatch

by com.supercatch
OverviewDiscussionsAdmin

Add this listing's product to my watchlist

supercatch_create_watchlist_item
Idempotent

Ensure the product represented by one exact eligible public listing is in the account watchlist at the target snapshot version. If a typed catalog product is already represented by a watched sibling listing, the result is unchanged rather than adding a duplicate. Use only when the account holder explicitly asks to watch the product represented by this exact eligible listing. Read the current target snapshot first and pass its exact version. An already-watched sibling listing for the same typed catalog product makes this add an unchanged no-op. This does not change wanted-item alerts or notification preferences, price targets, purchase history, seller listings or catalog data. A strict account.watchlist.change receipt with the exact membership revision and bounded affected native membership IDs. Requires OAuth account:watchlist:write consent. This is a direct low-impact membership change; it does not require a separate approval plan. Account reads and seller grants do not substitute for account:watchlist:write consent. Ensures the account has a watchlist membership for the target's typed catalog product, or for the exact unlinked listing. An existing same-product sibling membership is treated as already present. The durable receipt is atomic; alert preferences, notifications and purchases are untouched, and cache refresh is reported separately. Requires the independent account:watchlist:write grant and current account authority. Unknown or stale targets fail closed. Add requires current public eligibility; inspect or remove can use a nonpublic listing only when this account has a membership. Removal refuses more than 20 sibling rows instead of partially deleting them. Keep the original idempotency key after an uncertain response and recover with supercatch_list_operations using action account.watchlist.change, then inspect supercatch_get_operation. Do not retry with a replacement key.

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": {
      "listing_id": "public-listing-id",
      "idempotency_key": "watchlist-add-example-001",
      "expected_version": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
    },
    "name": "supercatch_create_watchlist_item"
  }
}

Input Schema

NameRequiredDescriptionDefault
listing_idYesThe exact listing returned by supercatch_get_watchlist_target.
idempotency_keyYesStable client-generated key for this exact intent. Reuse it after a lost response; a different intent must use a new key.
expected_versionYesSHA-256 of the exact current target snapshot returned by supercatch_get_watchlist_target. Reread after any version conflict.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare non-readOnly, idempotent and non-destructive, yet the description adds far more: the duplicate-sibling no-op, the explicit non-effects (alerts, notification preferences, price targets, purchase history, seller listings, catalog data), OAuth scope requirement, atomicity of the receipt, fail-closed behavior on stale/unknown targets, and a recovery procedure using supercatch_list_operations and supercatch_get_operation. This is unusually rich behavioral disclosure that goes well past the structured hints.

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 purpose is front-loaded, but the body is heavily redundant: the sibling no-op rule is stated three separate times, the account:watchlist:write requirement is repeated three times, and the receipt/atomicity claim appears twice. It also includes a clause about removal refusing more than 20 sibling rows that belongs to a different tool and dilutes focus.

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

Completeness4/5

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

Given a mutation tool with an output schema, three required parameters, and annotations covering idempotency and safety, the description covers auth, preconditions, failure modes, duplication semantics, and uncertain-response recovery. Completeness is high; the only shortfall is that the stray removal-limit clause and repeated statements blur rather than extend the picture.

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 description coverage is 100%, so the baseline is 3, but the text contributes operational meaning the schema lacks: it stresses re-reading the snapshot on conflict, and it specifies that the original idempotency key must be reused after an uncertain response ('Do not retry with a replacement key'), which materially changes how the required key should be handled.

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 action and resource with precise scope: 'Ensure the product represented by one exact eligible public listing is in the account watchlist at the target snapshot version.' It also distinguishes the catalog-product vs. exact-listing identity model, which separates it from list_account_watchlist, delete_watchlist_item, and get_watchlist_target.

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 an explicit when-to-use gate ('Use only when the account holder explicitly asks to watch the product represented by this exact eligible listing') and a mandatory precondition sequence ('Read the current target snapshot first and pass its exact version'). It also explains the no-op outcome for watched siblings, but never names the sibling tool for the inverse operation (removal) or for ordinary listing inspection, leaving that routing to inference.

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

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