Skip to main content
Glama

Search products

search_products
Read-only

Answer one free-text shopping query, such as 'TVs under $500 with 120hz refresh rate', 'quiet dishwasher for a small kitchen', 'robot vacuum for pet hair under $600', or 'Sony WH-1000XM5 lowest price'. A query naming one specific product resolves to that product (interpretation.mode 'product'): products[0] holds every seller offer, and shelf_context gives its shelf rank and higher-scoring alternatives. 'A vs B' returns both products with specs in one shared order (mode 'comparison'). Otherwise the category is resolved, hard constraints such as price and specs become filters, and soft wishes such as 'quiet' or 'for pet hair' become ranking preferences that exclude nothing; interpretation.preferences lists them with reasons, and each row's preference_boost shows the effect. The interpretation object records how the query was read: method (deterministic parser or query-understanding model), fit_note (a one-line judgment of the category fit), and match_quality. 'strong' means the shelf plainly fits. 'partial' means either rows are served with some shopper words unexplained (listed in unparsed_tokens and unsupported_terms), or no rows are served because the closest shelf was only a medium-confidence fit (named in interpretation.llm_category). 'weak' and 'none' return no rows and queue the request as demand (queued_for_creation for a missing category, queued_product_request for a missing product). card_specs gives the specs every product card shows, in display order. type_filter lists the shelf's product types with row counts. Responses that carry buy_url links also carry a disclosure field: the commission disclosure for those links.

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
sortNo
limitNo
queryYes
cursorNo
user_signatureNoOptional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / user_signature / description
      Previous value: -"Optional opaque, stable, pseudonymous user id that personalizes ranking. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."New value: +"Optional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."
  2. First observed

TDQS

A3.5/5.0
Behavior4/5

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries most of the behavioral burden and does so well: it discloses the interpretation object's fields, the meaning of strong/partial/weak/none match_quality, that weak/none return no rows, the demand-queue side effects (queued_for_creation, queued_product_request), and the commission disclosure attached to buy_url. The only shortfall is that these behaviors are buried in a dense narrative rather than surfaced as distinct traits; the demand-queue behavior is a genuine side effect not reflected in readOnlyHint, but it is logging-style rather than data mutation, so it is not a contradiction.

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?

Front-loaded with the verb and examples, and nearly every sentence introduces new information — necessary because there is no output schema. It is still a single dense block covering interpretation, match_quality, queueing, specs, filters, and disclosure, which makes it hard to scan, but there is little outright filler.

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?

With no output schema, the description properly spends its budget explaining return shape — products[0], shelf_context, interpretation, card_specs, type_filter, preference_boost. It is complete about results and edge cases, but silent on pagination (cursor) and sorting controls, which an agent needs to iterate results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 20% — only user_signature is documented in the schema. The description never mentions sort, limit, cursor, or query, so four of five parameters receive no added meaning from either source, and the undocumented cursor/sort interaction with the described ranking behavior is left entirely to inference.

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?

'Answer one free-text shopping query' gives a specific verb and resource, and the four worked query shapes ('TVs under $500 with 120hz', 'quiet dishwasher', 'A vs B', 'Sony WH-1000XM5 lowest price') make the scope concrete. It does not explicitly contrast itself with siblings like get_products or lookup_product, so the agent must infer that those handle non-free-text or single-product paths.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through query examples and the mode mapping (product / comparison / category resolution), which helps an agent recognize eligible inputs. However, there is no explicit 'use this when X, use lookup_product when Y' routing, and nothing states when not to call it.

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.