AirShelf Catalog

Discover and verify products for a need

find_products

Read-only

Discover candidate products for a buyer need. Takes a need in natural language (e.g. "best value home espresso machine", market "TH"), Unless the need is out of scope or live discovery is off or rate-limited, each call reads the verified catalog and also runs live web discovery, which sends the need text to web-search providers. A confirmed live result is returned when there is one; catalog candidates are returned instead when live discovery is unavailable, rate-limited, fails, or confirms no fit. Returns up to 3 candidates with explicit fit accounting.

find_products is the quick candidate-list tool; research_shopping is the full verified-research job. For a specific brand+model, search_catalog is cheaper and returns the same live-lookup block on a miss.

Response fields: • candidates[].verification — "catalog-verified" for a catalog row whose stated requirements each have a receipt, "catalog-candidate" for a catalog starting point whose fit still needs checking, or "live-unverified" for a live page read during this run. • candidates[].status — "resolved" means both identity and the parsed buyer constraints were supported by the cited page; "abstain" means identity or need fit could not be established. Inspect constraint_check for matched, conflicting, and unverified requirements. • candidates[].constraint_check.receipts maps each receipt-backed matched requirement to its supporting source URL and trust label. • Live candidates come from current web-search results, so they are a sample of what the market offers rather than a ranking. • status at the top level — "no_match" means no candidate was confirmed as satisfying the need; "disabled" means live discovery is off and no candidates are returned; "rate_limited" or "unavailable" means no discovery ran and no catalog candidate was found.

• live_discovery.status="unavailable" means receipted catalog candidates were returned while live discovery was unavailable.

Optional market (ISO 3166-1 alpha-2) biases discovery and marketplace checks toward seller pages serving that country and scopes the lookup cache. "Available in " means the seller page serves that market, not that stock is guaranteed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "need": "<need>"
    },
    "name": "find_products"
  }
}

Input Schema

Name	Required	Description
`max`	No	Max candidates to verify (each costs a live lookup; capped at 3).
`need`	Yes	The buyer need in natural language, e.g. "quiet mechanical keyboard for open office" or "best value home espresso machine".
`market`	No	Buyer market as ISO 3166-1 alpha-2 country code (e.g. "TH"). Biases discovery and marketplace checks toward seller pages serving that country and scopes the cache; availability is not a stock guarantee.

Output Schema

Name	Required	Description	Default
`need`	No
`error`	No
`market`	No
`reason`	No
`status`	No
`took_ms`	No
`guidance`	No
`candidates`	Yes
`verification`	No
`live_discovery`	No
`serp_considered`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedAug 12, 2026

addedOutput schema / properties / live_discovery

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "guidance": {
+      "type": "string"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "const": "unavailable",
+      "type": "string"
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

Changed1 schema field changedAug 12, 2026

changedOutput schema / properties / status / enum

Previous value: -[
-  "ok",
-  "no_match",
-  "disabled",
-  "rate_limited",
-  "error",
-  "refused"
-]New value: +[
+  "ok",
+  "no_match",
+  "disabled",
+  "rate_limited",
+  "unavailable",
+  "error",
+  "refused"
+]

Changed1 schema field changedAug 9, 2026

changedOutput schema / properties / status / enum

Previous value: -[
-  "ok",
-  "no_match",
-  "disabled",
-  "rate_limited",
-  "error"
-]New value: +[
+  "ok",
+  "no_match",
+  "disabled",
+  "rate_limited",
+  "error",
+  "refused"
+]

Changed1 schema field changedAug 9, 2026
- addedOutput schema / properties / reason
```
Added value: +{
+  "type": "string"
+}
```

Changed1 schema field changedAug 7, 2026

changedOutput schema / properties / status / enum

Previous value: -[
-  "ok",
-  "disabled",
-  "rate_limited",
-  "error"
-]New value: +[
+  "ok",
+  "no_match",
+  "disabled",
+  "rate_limited",
+  "error"
+]

Changed3 schema fields changedAug 5, 2026

removedInput schema / properties / market / pattern
```
Removed value: -"^[A-Za-z]{2}$"
```

changedOutput schema / properties / candidates / items / properties / status / enum

Previous value: -[
-  "resolved",
-  "abstain"
-]New value: +[
+  "resolved",
+  "abstain",
+  "declined"
+]

changedOutput schema / properties / candidates / items / required

Previous value: -[
-  "query",
-  "tier",
-  "status",
-  "guidance",
-  "verification"
-]New value: +[
+  "query",
+  "tier",
+  "status"
+]

Changed1 schema field changedAug 4, 2026

changedInput schema / properties / market / description

Previous value: -"Buyer market as ISO 3166-1 alpha-2 country code (e.g. \"TH\"). Biases discovery + verification and scopes the cache."New value: +"Buyer market as ISO 3166-1 alpha-2 country code (e.g. \"TH\"). Biases discovery and marketplace checks toward seller pages serving that country and scopes the cache; availability is not a stock guarantee."

AddedJul 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the readOnly/openWorld annotations: it discloses that each call sends the need text to web-search providers (a real privacy/egress signal), that live results are a sample not a ranking, and how fallback behaves when discovery is rate-limited, unavailable, fails, or finds no fit.

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 opening two sentences and the sibling routing are well front-loaded, but the large bulleted response-fields block largely restates a return contract that an output schema already declares, making the definition noticeably heavier than needed for the decision it supports.

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?

For a three-parameter, open-world, live-network tool the description is nearly complete: degradation states, candidate status semantics, and egress are all covered. It is slightly over-complete on return values that the output schema already carries, which is redundancy rather than a gap.

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 baseline is 3; the description earns an extra point by clarifying what market actually means ('Available in <market>' means the seller page serves that market, not a stock guarantee) and by explaining the cap on max via 'Returns up to 3 candidates'.

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 (discover) and resource (candidate products) plus the input form (natural-language need, market). It also positions itself precisely against siblings: 'find_products is the quick candidate-list tool; research_shopping is the full verified-research job' and search_catalog for a specific brand+model.

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?

Explicit alternatives with selection conditions are given for both siblings (research_shopping for full research, search_catalog when a specific brand+model is known and cheaper). The description also names exclusions — out-of-scope needs, live discovery off, rate-limited — so an agent knows when the tool degrades or does not run.

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

All AirShelf Catalog 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?