Skip to main content
Glama

mcp-gateway

by xyz.trusteed
OverviewDiscussionsAdmin

search_products

Read-onlyIdempotent

Search products in Demo Store. Returns matching products with prices, images, availability, and direct links. Results include data for generating a visual product carousel artifact with category filtering.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoNumber of results (1-50)
queryNoSearch query (e.g. 'red sneakers', 'winter jacket'). Omit to list all products.
cursorNoOpaque pagination cursor from next_cursor of a previous response. Only valid for the SAME query, category, price range and sort_by — a cursor replayed against different filters is rejected, not silently applied.
compactNoWhen true, the same products are described only once instead of twice. `structuredContent.products` stays the full typed record — every field, every product, untouched — but the text reply becomes a short id/title/price/currency/availability line per product instead of a markdown re-narration of that same data (images, links, ratings inline), and the duplicate `_carousel`/`_ui` widget payload is left out. Nothing that asserts trust is affected: `merchant_trust`, `rating_provenance` and `sort_provenance_warning` are never trimmed by this flag. Ignored when `field_mask` is also set — a field mask already replaces the narration with a compact listing and drops the widget payload, so there is nothing left for `compact` to cut.
sort_byNoSort order for resultsrelevance
categoryNoFilter by category slug
max_priceNoMaximum price filter
min_priceNoMinimum price filter
field_maskNoReturn only these product fields, to spend less of your context on a large catalogue. `id` is always included. Supplying a mask also drops the carousel/UI payloads, which are the bulk of a full response.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryNo
totalYes
has_moreNo
productsYes
_carouselNo
next_cursorNo
store_environmentNo
sort_provenance_warningNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / _carousel / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / products / items / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / properties / products / items / properties / rating_provenance / anyOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "note": {
-        "type": "string"
-      },
-      "origin": {
-        "const": "merchant",
-        "type": "string"
-      },
-      "strength": {
-        "const": "claimed",
-        "type": "string"
-      },
-      "verified": {
-        "const": false,
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "origin",
-      "strength",
-      "verified",
-      "note"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": true,
+    "properties": {
+      "note": {
+        "type": "string"
+      },
+      "origin": {
+        "const": "merchant",
+        "type": "string"
+      },
+      "strength": {
+        "const": "claimed",
+        "type": "string"
+      },
+      "verified": {
+        "const": false,
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "origin",
+      "strength",
+      "verified",
+      "note"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
  2. Changed1 schema field changed
    • addedInput schema / properties / compact
      Added value: +{
+  "default": false,
+  "description": "When true, the same products are described only once instead of twice. `structuredContent.products` stays the full typed record — every field, every product, untouched — but the text reply becomes a short id/title/price/currency/availability line per product instead of a markdown re-narration of that same data (images, links, ratings inline), and the duplicate `_carousel`/`_ui` widget payload is left out. Nothing that asserts trust is affected: `merchant_trust`, `rating_provenance` and `sort_provenance_warning` are never trimmed by this flag. Ignored when `field_mask` is also set — a field mask already replaces the narration with a compact listing and drops the widget payload, so there is nothing left for `compact` to cut.",
+  "type": "boolean"
+}
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "_carousel": {
+      "additionalProperties": false,
+      "properties": {
+        "apiEndpoint": {
+          "type": "string"
+        },
+        "initialCategory": {
+          "type": "string"
+        },
+        "productsForArtifact": {
+          "items": {},
+          "type": "array"
+        },
+        "storeSlug": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "apiEndpoint",
+        "storeSlug",
+        "productsForArtifact",
+        "initialCategory"
+      ],
+      "type": "object"
+    },
+    "has_more": {
+      "type": "boolean"
+    },
+    "next_cursor": {
+      "type": "string"
+    },
+    "products": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "compareAtPrice": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "currency": {
+            "type": "string"
+          },
+          "id": {
+            "description": "Product ID — use as product_id in create_cart",
+            "type": "string"
+          },
+          "image": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "price": {
+            "type": "number"
+          },
+          "rating": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "rating_provenance": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "note": {
+                    "type": "string"
+                  },
+                  "origin": {
+                    "const": "merchant",
+                    "type": "string"
+                  },
+                  "strength": {
+                    "const": "claimed",
+                    "type": "string"
+                  },
+                  "verified": {
+                    "const": false,
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "origin",
+                  "strength",
+                  "verified",
+                  "note"
+                ],
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "reviewCount": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "stockStatus": {
+            "enum": [
+              "in_stock",
+              "low_stock",
+              "out_of_stock"
+            ],
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "vendor": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "query": {
+      "type": "string"
+    },
+    "sort_provenance_warning": {
+      "type": "string"
+    },
+    "store_environment": {
+      "type": "string"
+    },
+    "total": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "products",
+    "total"
+  ],
+  "type": "object"
+}
  4. Changed3 schema fields changed
    • addedInput schema / $schema
      Added value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties
      Added value: +{
+  "category": {
+    "description": "Filter by category slug",
+    "type": "string"
+  },
+  "cursor": {
+    "description": "Opaque pagination cursor from next_cursor of a previous response. Only valid for the SAME query, category, price range and sort_by — a cursor replayed against different filters is rejected, not silently applied.",
+    "type": "string"
+  },
+  "field_mask": {
+    "description": "Return only these product fields, to spend less of your context on a large catalogue. `id` is always included. Supplying a mask also drops the carousel/UI payloads, which are the bulk of a full response.",
+    "items": {
+      "enum": [
+        "title",
+        "price",
+        "compareAtPrice",
+        "currency",
+        "image",
+        "url",
+        "stockStatus",
+        "rating",
+        "reviewCount",
+        "rating_provenance",
+        "vendor"
+      ],
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "limit": {
+    "default": 10,
+    "description": "Number of results (1-50)",
+    "maximum": 50,
+    "minimum": 1,
+    "type": "integer"
+  },
+  "max_price": {
+    "description": "Maximum price filter",
+    "exclusiveMinimum": 0,
+    "type": "number"
+  },
+  "min_price": {
+    "description": "Minimum price filter",
+    "exclusiveMinimum": 0,
+    "type": "number"
+  },
+  "query": {
+    "description": "Search query (e.g. 'red sneakers', 'winter jacket'). Omit to list all products.",
+    "type": "string"
+  },
+  "sort_by": {
+    "default": "relevance",
+    "description": "Sort order for results",
+    "enum": [
+      "relevance",
+      "price_asc",
+      "price_desc",
+      "newest",
+      "rating"
+    ],
+    "type": "string"
+  }
+}
  5. Changed4 schema fields changed
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties
      Removed value: -{
-  "category": {
-    "description": "Filter by category slug",
-    "type": "string"
-  },
-  "limit": {
-    "default": 10,
-    "description": "Number of results (1-50)",
-    "maximum": 50,
-    "minimum": 1,
-    "type": "integer"
-  },
-  "max_price": {
-    "description": "Maximum price filter",
-    "exclusiveMinimum": 0,
-    "type": "number"
-  },
-  "min_price": {
-    "description": "Minimum price filter",
-    "exclusiveMinimum": 0,
-    "type": "number"
-  },
-  "query": {
-    "description": "Search query (e.g. 'red sneakers', 'winter jacket'). Omit to list all products.",
-    "type": "string"
-  },
-  "sort_by": {
-    "default": "relevance",
-    "description": "Sort order for results",
-    "enum": [
-      "relevance",
-      "price_asc",
-      "price_desc",
-      "newest",
-      "rating"
-    ],
-    "type": "string"
-  }
-}
    • changedOutput schema / (root)
      Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "_carousel": {
-      "additionalProperties": false,
-      "properties": {
-        "apiEndpoint": {
-          "type": "string"
-        },
-        "initialCategory": {
-          "type": "string"
-        },
-        "productsForArtifact": {
-          "items": {},
-          "type": "array"
-        },
-        "storeSlug": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "apiEndpoint",
-        "storeSlug",
-        "productsForArtifact",
-        "initialCategory"
-      ],
-      "type": "object"
-    },
-    "products": {
-      "items": {
-        "additionalProperties": false,
-        "properties": {
-          "compareAtPrice": {
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "currency": {
-            "type": "string"
-          },
-          "id": {
-            "description": "Product ID — use as product_id in create_cart",
-            "type": "string"
-          },
-          "image": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "price": {
-            "type": "number"
-          },
-          "rating": {
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "reviewCount": {
-            "type": [
-              "number",
-              "null"
-            ]
-          },
-          "stockStatus": {
-            "enum": [
-              "in_stock",
-              "low_stock",
-              "out_of_stock"
-            ],
-            "type": "string"
-          },
-          "title": {
-            "type": "string"
-          },
-          "url": {
-            "type": "string"
-          },
-          "vendor": {
-            "type": [
-              "string",
-              "null"
-            ]
-          }
-        },
-        "required": [
-          "id",
-          "title",
-          "price",
-          "compareAtPrice",
-          "currency",
-          "image",
-          "url",
-          "stockStatus",
-          "rating",
-          "reviewCount",
-          "vendor"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "query": {
-      "type": "string"
-    },
-    "total": {
-      "type": "number"
-    }
-  },
-  "required": [
-    "products",
-    "total"
-  ],
-  "type": "object"
-}New value: +null
  6. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the compact flag's effect on output, the field_mask's context-saving behavior, and the cursor's strict validity constraint (rejected if replayed against different filters). This goes beyond the annotations and schema.

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 front-loaded with the core purpose and return value, then dives into parameter-specific behavior. It is somewhat long, but every sentence adds meaningful detail about output shaping and pagination constraints. The structure is logical: purpose first, then output highlights, then parameter nuances.

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 the tool's complexity (9 parameters, output schema, rich annotations), the description covers the key behavioral nuances an agent needs: pagination cursor validity, compact vs. field_mask interaction, and trust-field preservation. It doesn't explicitly describe the output schema structure, but the output schema exists and the description references key fields. Minor gap: no explicit statement about when to prefer search_products_enriched, but overall complete for invocation.

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. The description adds meaningful semantics beyond the schema: it explains that 'compact' trims the text reply and drops widget payloads while preserving trust fields, and that 'field_mask' drops carousel/UI payloads and always includes 'id'. It also clarifies the cursor's strict binding to the same query/filters. This is more than the schema alone 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 description states a specific verb ('Search') and resource ('products in Demo Store'), and immediately distinguishes the tool from siblings by noting it returns prices, images, availability, and direct links, plus data for a visual carousel artifact. This clearly differentiates it from search_products_enriched and get_product_details.

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 implies usage for searching and listing products, and the sibling list includes search_products_enriched, which suggests a more enriched alternative, but the description does not explicitly state when to use this tool vs. search_products_enriched or get_product_details. It gives clear context for what it returns but no explicit exclusions or alternative routing.

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

All mcp-gateway 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