Skip to main content
Glama

Search products across independent stores

search_products
Read-onlyIdempotent

Searches US online stores' product catalogs for shopping requests such as product types, brands, budgets and gift ideas. It covers US stores for US shoppers only. Supply requestedBrandNames as an array of the complete brand names the shopper explicitly named, or an empty array when none is named. Each result describes a selected variant, with its Nobi variant ID (id and variantId), parent productId, merchantId, source IDs, name, store, catalog price and currency, stock status, image and link. People buy from the store. When linkLabel is set, such as "We may earn a commission", show it beside that product's link. For follow-up calls in this conversation, send the visitorId returned by a previous result unchanged. Omit it on the first call; do not invent one.

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": {
      "query": "<query>"
    },
    "name": "search_products"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoHow many products to return, from 1 to 20. The default is 10.
queryYesWhat the user is looking for, in plain words, with the details that matter to them, such as "waterproof hiking boots" or "linen dress for a summer wedding under $150".
visitorIdNoFor follow-up calls in this conversation, send the visitorId returned by a previous result unchanged. Omit it on the first call; do not invent one.
requestedBrandNamesNoWhen the shopper explicitly names brands or stores, list their complete names exactly as written, such as Regal Rose or Mirror Palais. Do not include colors, materials, styles, product types, or guessed brands. Use an empty list when none is named. This helps find the requested products even when a named brand is absent from this catalog.

Output Schema

NameRequiredDescriptionDefault
productsYes
visitorIdNoFor follow-up calls in this conversation, send the visitorId returned by a previous result unchanged. Omit it on the first call; do not invent one.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / requestedBrandNames
      Added value: +{
      +  "description": "When the shopper explicitly names brands or stores, list their complete names exactly as written, such as Regal Rose or Mirror Palais. Do not include colors, materials, styles, product types, or guessed brands. Use an empty list when none is named. This helps find the requested products even when a named brand is absent from this catalog.",
      +  "items": {
      +    "description": "When the shopper explicitly names brands or stores, list their complete names exactly as written, such as Regal Rose or Mirror Palais. Do not include colors, materials, styles, product types, or guessed brands. Use an empty list when none is named. This helps find the requested products even when a named brand is absent from this catalog.",
      +    "maxLength": 80,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 4,
      +  "type": "array"
      +}
  2. Changed2 schema fields changed
    • addedInput schema / properties / visitorId
      Added value: +{
      +  "description": "For follow-up calls in this conversation, send the visitorId returned by a previous result unchanged. Omit it on the first call; do not invent one.",
      +  "format": "uuid",
      +  "maxLength": 36,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedOutput schema / properties / visitorId
      Added value: +{
      +  "description": "For follow-up calls in this conversation, send the visitorId returned by a previous result unchanged. Omit it on the first call; do not invent one.",
      +  "format": "uuid",
      +  "maxLength": 36,
      +  "minLength": 1,
      +  "type": "string"
      +}
  3. Changed7 schema fields changed
    • addedOutput schema / properties / products / items / properties / id / description
      Added value: +"Legacy alias for the selected Nobi variantId; null for parent details. productId identifies the parent."
    • addedOutput schema / properties / products / items / properties / merchantId
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / products / items / properties / productId
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / products / items / properties / sourceProductId
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / products / items / properties / sourceVariantId
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / products / items / properties / variantId
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / properties / products / items / required
      Previous value: -[
      -  "id",
      -  "name",
      -  "store",
      -  "price",
      -  "currency",
      -  "inStock",
      -  "imageUrl",
      -  "url",
      -  "paidLink",
      -  "linkLabel"
      -]New value: +[
      +  "id",
      +  "name",
      +  "store",
      +  "price",
      +  "currency",
      +  "inStock",
      +  "imageUrl",
      +  "url",
      +  "paidLink",
      +  "linkLabel",
      +  "productId",
      +  "variantId",
      +  "merchantId",
      +  "sourceProductId",
      +  "sourceVariantId"
      +]
  4. Changed2 schema fields changed
    • addedOutput schema / properties / products / items / properties / id
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / properties / products / items / required
      Previous value: -[
      -  "name",
      -  "store",
      -  "price",
      -  "currency",
      -  "inStock",
      -  "imageUrl",
      -  "url",
      -  "paidLink",
      -  "linkLabel"
      -]New value: +[
      +  "id",
      +  "name",
      +  "store",
      +  "price",
      +  "currency",
      +  "inStock",
      +  "imageUrl",
      +  "url",
      +  "paidLink",
      +  "linkLabel"
      +]
  5. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavior beyond that: results are per-variant with parent product and merchant IDs, purchase happens at the merchant ("People buy from the store"), affiliate linkLabel must be surfaced, and visitorId must be threaded through follow-ups or omitted—none of which the annotations convey.

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 scope and result-shape sentences earn their place, but two sentences—the requestedBrandNames rule and the visitorId rule—are near-verbatim duplicates of the schema descriptions, and the result-field enumeration is verbose given an output schema exists. It is not rambling, but several clauses could be dropped without loss.

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 single-query search tool, the definition covers scope, input conventions, conversation continuity, and affiliate disclosure, which is enough for correct invocation. Return values are over-explained despite an existing output schema, and empty-result behavior is not mentioned, keeping it just short of fully complete.

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?

Schema coverage is 100%, so the schema already documents query, limit, visitorId, and requestedBrandNames. The description's brand-name guidance (complete names, no colors or guessed brands, empty array when none) and visitorId rule largely restate the schema text rather than adding new semantics, so the baseline of 3 applies.

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?

"Searches US online stores' product catalogs for shopping requests such as product types, brands, budgets and gift ideas" gives a concrete verb, resource, and geographic scope, which separates it from catalog-wide siblings like compare_products or find_alternatives. It never names an alternative explicitly, so the differentiation is inferred rather than stated.

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 states the context in which it applies (US shoppers, US stores) and gives concrete operating rules: supply complete brand names or an empty array, reuse visitorId on follow-ups, omit it on the first call, and render linkLabel when present. It stops short of saying when to prefer find_alternatives or compare_products instead.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources