SCVD General Store

Find Something on the Shelf

find_in_catalog

Read-onlyIdempotent

Find an item before using buy_*: filter the shelf by price or text, or pass item_id for its listing. Rows give USDC price, fulfillment and read scope. Free, read-only, no account. Results stay in shelf order; nothing is ranked or recommended. A listing is not a stock check. Invalid lookups return a free next_step.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	Words to match against an item's id, name, subtitle and description.
`item_id`	No	One item's id. It replaces search rather than narrowing it: q and max_price_usdc are not applied, and the answer is that one item in full.
`max_price_usdc`	No	A ceiling in USDC. Items at or below it match.

Output Schema

TableJSON Schema

Name	Required	Description
`of`	Yes	How many are on the shelf, the denominator.
`items`	Yes	The rows, in the shelf's own order.
`query`	No	The filter that was applied, echoed.
`scope`	No
`matched`	Yes	How many items matched.
`publications`	No	Publication indexes outside menu search; archived collections are opt-in, not current offerings.
`whole_catalogue`	No	The full catalogue, for a caller that wants every field.
`how_this_was_ordered`	No	That the order is the shelf's own and nothing is ranked.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 24, 2026

changedOutput schema / properties / items / items / properties / reads / description

Previous value: -"What the item reads: our_books, subject_fetch, made_here."New value: +"The declared class of observations this item makes."

Changed1 schema field changedSep 21, 2026

addedOutput schema / properties / items / items / properties / buy_url_template

Added value: +{
+  "description": "Where present, buy this instead: the door with its required inputs as <slot>s to fill.",
+  "format": "uri",
+  "type": "string"
+}

Changed2 schema fields changedSep 15, 2026

addedOutput schema / properties / publications

Added value: +{
+  "description": "Publication indexes outside menu search; archived collections are opt-in, not current offerings.",
+  "items": {
+    "properties": {
+      "index_url": {
+        "format": "uri",
+        "type": "string"
+      },
+      "status": {
+        "enum": [
+          "active",
+          "archived"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "index_url",
+      "status"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / scope

Added value: +{
+  "enum": [
+    "active_menu"
+  ],
+  "type": "string"
+}

Changed4 schema fields changedSep 6, 2026

changedInput schema / properties / item_id / description

Previous value: -"One item's id. The answer carries that item alone, in full."New value: +"One item's id. It replaces search rather than narrowing it: q and max_price_usdc are not applied, and the answer is that one item in full."

addedOutput schema / properties / items / items / description
```
Added value: +"One shelf row, in the shelf's own order."
```

addedOutput schema / properties / items / items / properties

Added value: +{
+  "buy_url": {
+    "description": "The x402 door that sells it.",
+    "format": "uri",
+    "type": "string"
+  },
+  "cadence": {
+    "description": "one_off, or the recurring shape.",
+    "type": "string"
+  },
+  "fulfillment": {
+    "description": "instant, or human-fulfilled with a window.",
+    "type": "string"
+  },
+  "id": {
+    "description": "The item id a buy_* call or item_id lookup takes.",
+    "type": "string"
+  },
+  "listing_url": {
+    "description": "The room that describes it in full.",
+    "format": "uri",
+    "type": "string"
+  },
+  "name": {
+    "description": "What the item is called.",
+    "type": "string"
+  },
+  "price_tiers_usdc": {
+    "description": "Every price this item is sold at, cheapest first.",
+    "items": {
+      "type": "number"
+    },
+    "type": "array"
+  },
+  "price_usdc": {
+    "description": "The lowest price on this row, in USDC.",
+    "type": "number"
+  },
+  "reads": {
+    "description": "What the item reads: our_books, subject_fetch, made_here.",
+    "type": "string"
+  },
+  "subtitle": {
+    "description": "The one-line gloss, when the item has one.",
+    "type": "string"
+  }
+}

addedOutput schema / properties / items / items / required

Added value: +[
+  "id",
+  "name",
+  "price_usdc",
+  "cadence",
+  "fulfillment",
+  "reads",
+  "buy_url",
+  "listing_url"
+]

AddedSep 6, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral details: it's free, requires no account, results stay in shelf order, nothing is ranked or recommended, and a listing is not a stock check. These are not inferable from the annotations alone and help the agent set expectations for the response.

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

Conciseness5/5

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

The description is only four sentences but packs in purpose, usage, behavior, and constraints. It front-loads the primary intent and keeps each sentence purposeful with no redundancy. It is concise and well-structured for quick comprehension.

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 the tool has an output schema, the description need not explain return values. It covers the main scenarios (filter by price/text, or item_id), notes the ordering and ranking behavior, clarifies the 'not a stock check' limitation, and explains error responses. This is comprehensive for an agent to call the tool correctly.

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?

The schema descriptions for all three parameters are 100% covered, so the baseline is 3. The tool description adds minimal new meaning beyond summarizing the three modes (price, text, item_id) and their effects. It doesn't introduce details not already in the schema, so it does not exceed the baseline.

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 description clearly states the tool's purpose: 'Find an item before using buy_*', which is a specific verb (find) and resource (catalog). It also mentions the filtering modes (price, text, item_id) and distinguishes it from the buy_* siblings by positioning it as a prerequisite. This makes the tool's role unambiguous.

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?

The description explicitly instructs when to use this tool: 'Find an item before using buy_*'. It also clarifies limitations like 'A listing is not a stock check' and 'Results stay in shelf order; nothing is ranked or recommended', which helps the agent decide if this is the right tool for a given query. The sentence 'Invalid lookups return a free next_step' also informs error handling.

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

All SCVD General Store 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.