Skip to main content
Glama

AirShelf Catalog

by ai.airshelf
OverviewDiscussionsAdmin

Search product catalog

search_catalog
Read-only

Search the AirShelf cross-vendor product catalog by natural-language query. The catalog covers industrial-automation, wiring-devices, digital-signage, business-display, mfp, barcode-printer, laser-printer, inkjet-printer, mechanical-keyboards, cybersecurity, threat-intelligence-platform. Industrial-automation and wiring-device rows are indexed by manufacturer part number, so a brand or part number in the query ("Pepperl+Fuchs retroreflective sensor", "IN5409") retrieves more reliably than a bare product type; those rows carry no normalized spec facets, so the specs filter does not apply to them. Returns ranked products with prices, specs, and per-row match accounting. Each row includes unverified_specs, the normalized spec names that lack claim-level receipts; never use those as decisive facts. Example queries: "tactile mechanical keyboard under $150", "Toshiba A3 colour multifunction device", "industrial barcode printer for a warehouse", "threat-intelligence platform with dark-web monitoring".

Result fields: • canonical_name — the exact catalog name of the product. • spec_absence_note — spec fields absent from this product's golden record (AirShelf's verified product record); null when nothing is missing. • constraint_match_score and matched_criteria — query constraints supported by claim-level receipts. unverified_criteria names matching catalog values that still need confirmation; missing_criteria names values that are absent or conflict. • parsed.price_availability — all_null = true means every returned price is null. For quote-gated B2B pricing, a null price with a quote path is expected rather than an error; query_had_budget reports whether the query carried one. • result.commercial_data — branch on actionable before using price or stock. Observations older than 24 hours are withheld from result.price/result.inStock and retained only as labelled last_observed history. • parsed.weak_match — the response contains an unresolved constraint, query match, or product-identity warning. parsed.unverified_identity_count counts returned names without an identity receipt. parsed.no_match — no product satisfies a hard constraint, and candidates violating it were excluded server-side.

On a miss or near-miss for a specific brand+model the response may also carry a tier3 block, meaning a real-time lookup for the exact SKU asked about; it can appear alongside fuzzy-neighbour rows. • tier3.status = "resolved" — a single-source reading of the page at tier3.source_url. MPN-confirmed means the live lookup matched the manufacturer part number. Its verification is "live-unverified": confirmed on a live page during this run, but not yet matched to an AirShelf catalog record. A verified row is matched to the catalog record. tier3.cached = true means it came from a recent prior lookup, with fetched_at recording when the page was read. • tier3.status = "abstain" — the lookup could not confirm the product exists as asked, so no specs, price, or availability were established. tier3.guidance describes the quote-request path. • tier3.status = "declined" — an applicable lookup did not run; tier3.reason says why (disabled, rate_limited, daily_cap, negative_cache, error). No specs or availability were established, and none should be inferred. No tier3 block at all means a live lookup was not applicable to this query (no parseable brand+model identity).

Optional market (ISO 3166-1 alpha-2, e.g. "TH") excludes catalog rows whose country-specific URL conflicts with the buyer market and scopes tier3 lookup/cache. A remaining global URL is not local-availability proof: parsed.weak_match stays true and unsatisfied_constraints includes market_availability until every returned row has a matching country receipt. "Available in " still does not guarantee stock.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qYesNatural-language query, at most 200 characters. Supports budget hints (e.g. "under $150").
limitNoMax results
specsNoHard spec facets, e.g. {"form_factor":"desktop","print_speed_ppm":33}. Filters by exact/range spec match.
marketNoBuyer market as an assigned ISO 3166-1 alpha-2 country code (e.g. "TH", "AU"). Conflicting country receipts are excluded; global URLs remain market-unverified.
categoryNoOptional category filter (industrial-automation, wiring-devices, digital-signage, business-display, mfp, barcode-printer, laser-printer, inkjet-printer, mechanical-keyboards, cybersecurity, threat-intelligence-platform)
merchantNoOptional merchant slug (e.g. "toshiba", "cyble") from list_merchants. Scopes the search to that merchant's own shelf, which is a SEPARATE substrate from the cross-vendor catalog: it is reached only when the cross-vendor catalog returns nothing, and its rows carry the merchant's own product data rather than datasheet-extracted golden records. Omit it for cross-vendor search, which is the default and the right choice for "what should I buy".

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNo
queryNo
tier3No
parsedNo
reasonNo
statusNo
resultsYes
took_msNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / merchant
      Added value: +{
+  "description": "Optional merchant slug (e.g. \"toshiba\", \"cyble\") from list_merchants. Scopes the search to that merchant's own shelf, which is a SEPARATE substrate from the cross-vendor catalog: it is reached only when the cross-vendor catalog returns nothing, and its rows carry the merchant's own product data rather than datasheet-extracted golden records. Omit it for cross-vendor search, which is the default and the right choice for \"what should I buy\".",
+  "pattern": "^[a-z0-9][a-z0-9-]{0,62}$",
+  "type": "string"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / category / description
      Previous value: -"Optional category filter (industrial-automation, wiring-devices, digital-signage, business-display, mechanical-keyboards, mfp, barcode-printer, laser-printer, inkjet-printer, cybersecurity, or threat-intelligence-platform)"New value: +"Optional category filter (industrial-automation, wiring-devices, digital-signage, business-display, mfp, barcode-printer, laser-printer, inkjet-printer, mechanical-keyboards, cybersecurity, threat-intelligence-platform)"
  3. Changed1 schema field changed
    • changedInput schema / properties / category / description
      Previous value: -"Optional category filter (industrial-automation, wiring-devices, mechanical-keyboards, mfp, barcode-printer, laser-printer, inkjet-printer, cybersecurity, or threat-intelligence-platform)"New value: +"Optional category filter (industrial-automation, wiring-devices, digital-signage, business-display, mechanical-keyboards, mfp, barcode-printer, laser-printer, inkjet-printer, cybersecurity, or threat-intelligence-platform)"
  4. Changed1 schema field changed
    • changedInput schema / properties / category / description
      Previous value: -"Optional category filter (industrial-automation, wiring-devices, mechanical-keyboards, mfp, barcode-printer, laser-printer, cybersecurity, or threat-intelligence-platform)"New value: +"Optional category filter (industrial-automation, wiring-devices, mechanical-keyboards, mfp, barcode-printer, laser-printer, inkjet-printer, cybersecurity, or threat-intelligence-platform)"
  5. Changed1 schema field changed
    • changedInput schema / properties / category / description
      Previous value: -"Optional category filter (mechanical-keyboards, mfp, barcode-printer, laser-printer, cybersecurity, or threat-intelligence-platform)"New value: +"Optional category filter (industrial-automation, wiring-devices, mechanical-keyboards, mfp, barcode-printer, laser-printer, cybersecurity, or threat-intelligence-platform)"
  6. Changed2 schema fields changed
    • addedOutput schema / properties / reason
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / status
      Added value: +{
+  "enum": [
+    "refused"
+  ],
+  "type": "string"
+}
  7. Changed1 schema field changed
    • changedInput schema / properties / market / description
      Previous value: -"Buyer market as an assigned ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). It affects only tier3 live lookup and does not filter or rank global catalog rows."New value: +"Buyer market as an assigned ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). Conflicting country receipts are excluded; global URLs remain market-unverified."
  8. Changed1 schema field changed
    • addedInput schema / properties / q / minLength
      Added value: +0
  9. Changed3 schema fields changed
    • changedInput schema / properties / market / description
      Previous value: -"Buyer market as an assigned ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). It affects only tier3 live lookup, not global catalog rows."New value: +"Buyer market as an assigned ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). It affects only tier3 live lookup and does not filter or rank global catalog rows."
    • changedInput schema / properties / q / description
      Previous value: -"Natural-language query. Supports budget hints (e.g. \"under $150\")."New value: +"Natural-language query, at most 200 characters. Supports budget hints (e.g. \"under $150\")."
    • addedInput schema / properties / q / maxLength
      Added value: +200
  10. Changed5 schema fields changed
    • changedInput schema / properties / category / description
      Previous value: -"Optional category filter (e.g. laser-printer, skincare, mechanical-keyboards)"New value: +"Optional category filter (mechanical-keyboards, mfp, barcode-printer, laser-printer, cybersecurity, or threat-intelligence-platform)"
    • changedInput schema / properties / market / description
      Previous value: -"Buyer market as ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). Biases the live lookup toward seller pages serving that country and scopes its cache; availability means market service, not guaranteed stock."New value: +"Buyer market as an assigned ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). It affects only tier3 live lookup, not global catalog rows."
    • removedInput schema / properties / market / pattern
      Removed value: -"^[A-Za-z]{2}$"
    • changedOutput schema / properties / tier3 / properties / status / enum
      Previous value: -[
-  "resolved",
-  "abstain"
-]New value: +[
+  "resolved",
+  "abstain",
+  "declined"
+]
    • changedOutput schema / properties / tier3 / required
      Previous value: -[
-  "tier",
-  "status",
-  "guidance",
-  "verification"
-]New value: +[
+  "tier",
+  "status"
+]
  11. Changed1 schema field changed
    • changedInput schema / properties / market / description
      Previous value: -"Buyer market as ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). Biases the tier3 live lookup toward that market and scopes its cache. Pass whenever the buyer's location is known."New value: +"Buyer market as ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). Biases the live lookup toward seller pages serving that country and scopes its cache; availability means market service, not guaranteed stock."
  12. Changed2 schema fields changed
    • changedInput schema / properties / category / description
      Previous value: -"Optional category filter (e.g. mechanical-keyboards)"New value: +"Optional category filter (e.g. laser-printer, skincare, mechanical-keyboards)"
    • changedInput schema / properties / q / description
      Previous value: -"Natural-language query. Supports budget (\"under $150\") and switch-type hints."New value: +"Natural-language query. Supports budget hints (e.g. \"under $150\")."
  13. Changed1 schema field changed
    • addedInput schema / properties / market
      Added value: +{
+  "description": "Buyer market as ISO 3166-1 alpha-2 country code (e.g. \"TH\", \"AU\"). Biases the tier3 live lookup toward that market and scopes its cache. Pass whenever the buyer's location is known.",
+  "pattern": "^[A-Za-z]{2}$",
+  "type": "string"
+}
  14. Changed1 schema field changed
    • addedOutput schema / properties / tier3 / properties / cached
      Added value: +{
+  "type": "boolean"
+}
  15. Changed1 schema field changed
    • addedOutput schema / properties / tier3
      Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "guidance": {
+      "type": "string"
+    },
+    "identity": {
+      "additionalProperties": false,
+      "properties": {
+        "brand": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "brand",
+        "model"
+      ],
+      "type": "object"
+    },
+    "mpn_confirmed": {
+      "type": "boolean"
+    },
+    "product": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "source_tier": {
+      "type": "string"
+    },
+    "source_url": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "resolved",
+        "abstain"
+      ],
+      "type": "string"
+    },
+    "tier": {
+      "type": "number"
+    },
+    "verification": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "tier",
+    "status",
+    "guidance",
+    "verification"
+  ],
+  "type": "object"
+}
  16. Changed3 schema fields changed
    • addedOutput schema / properties / parsed
      Added value: +{
+  "additionalProperties": {},
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
    • changedOutput schema / properties / results / items / required
      Previous value: -[
-  "slug",
-  "canonical_name"
-]New value: +[
+  "slug"
+]
    • addedOutput schema / properties / took_ms
      Added value: +{
+  "type": "number"
+}
  17. Changed2 schema fields changed
    • addedOutput schema / properties / results / items / properties / currency / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • removedOutput schema / properties / results / items / properties / currency / type
      Removed value: -"string"
  18. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "count": {
+      "type": "number"
+    },
+    "query": {
+      "type": "string"
+    },
+    "results": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "canonical_name": {
+            "type": "string"
+          },
+          "category": {
+            "type": "string"
+          },
+          "constraint_match_score": {
+            "type": "number"
+          },
+          "currency": {
+            "type": "string"
+          },
+          "manufacturer": {
+            "type": "string"
+          },
+          "modelName": {
+            "type": "string"
+          },
+          "price": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "qualityScore": {
+            "type": "number"
+          },
+          "slug": {
+            "type": "string"
+          },
+          "spec_absence_note": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "slug",
+          "canonical_name"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "results"
+  ],
+  "type": "object"
+}
  19. Changed1 schema field changed
    • addedInput schema / properties / specs
      Added value: +{
+  "additionalProperties": {
+    "anyOf": [
+      {
+        "type": "number"
+      },
+      {
+        "type": "string"
+      },
+      {
+        "type": "boolean"
+      }
+    ]
+  },
+  "description": "Hard spec facets, e.g. {\"form_factor\":\"desktop\",\"print_speed_ppm\":33}. Filters by exact/range spec match.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
  20. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Even though the annotations already mark this as safe and read-only, the description adds substantial behavioral nuance: unverified_specs must not be treated as decisive, null prices can be expected for quote-gated B2B pricing, data older than 24 hours is withheld, tier3 lookup statuses are explained, and market availability semantics are detailed. No contradiction with the annotations.

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

Conciseness4/5

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

The description is long but well-structured, front-loads the purpose, and uses bullet-style field explanations that are easy to scan. Some result-field detail may overlap with what the output schema already conveys, but the behavioral caveats around unverified data and tier3 statuses justify most of the length.

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 search tool with 6 parameters, nested outputs, and subtle edge cases, this description is remarkably complete. It explains query construction, result interpretation, no-match behavior, unavailable-price semantics, market verification, and the tier3 fallback path, leaving an agent well equipped to call the tool and interpret responses correctly.

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 then adds value by explaining that brand/part-number queries retrieve more reliably for certain rows, that the specs filter does not apply to those rows, and by providing example queries and deeper market-parameter behavior. It does not add much for limit or category, but the schema already describes those adequately.

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 description opens with a specific verb and resource: 'Search the AirShelf cross-vendor product catalog by natural-language query.' It distinguishes the cross-vendor catalog from the merchant-specific shelf described in the merchant parameter, but it does not explicitly differentiate this tool from sibling search-like tools such as find_products or research_shopping.

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?

The description gives clear context for use: cross-vendor search is the default and 'the right choice for "what should I buy"'. It also explains when the merchant-specific shelf is reached and the conditions around tier3 live lookups. However, it does not state explicit 'use this instead of X' exclusions for sibling tools.

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

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