Skip to main content
Glama

Search products

search_products
Read-onlyIdempotent

Search marketplace products by text and filters to compare prices, ratings, and reviews; returns product cards, total counts, and optional categories/facets for narrowing results.

Instructions

Search a marketplace for products by text and/or filters. Returns product cards (id, title, lowest price, rating, review count, link), the total count, and on request the available categories and facets whose value ids can be passed back in filters to narrow the search. Pages are 0-based.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_products"
  }
}

Input Schema

NameRequiredDescriptionDefault
cityNoCity name, code or id (e.g. 'Алматы', 'almaty', '750000000'). Prices, sellers and delivery depend on it. Omit to use the configured default city. Ask the user where they are if it matters and is unknown.
pageNo0-based page number.
sortNoSort order; see sortOptions in list_marketplaces (e.g. relevance, price-asc, price-desc, rating, created-desc).
queryNoSearch text. May be omitted when browsing by `filters` only.
filtersNoCategory/facet value ids exactly as returned in `categories` or `facets` of a previous search, e.g. [':category:Smartphones', ':manufacturerName:Apple'].
marketplaceNoMarketplace id from list_marketplaces.kaspi
include_facetsNoAlso return categories and facets available for this search (larger response; first page only).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior, so the description is not needed for the safety profile. It nonetheless adds real behavioral context: exact return contents (product cards with id, title, lowest price, rating, review count, link), the total count, and the fact that facets inflate the response and are first-page only.

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 action, then the return shape, then the paging caveat; no filler or marketing language. The middle clause is long and stacks three ideas (cards, total count, facets) in one sentence, which slightly hurts scannability but wastes no words.

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 usefully compensates by enumerating the returned fields and the total count, which an agent needs to plan follow-up calls. Remaining gaps are modest: page-size/result-cap behavior, what total count refers to under filters, and whether an empty result is an error are unstated.

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 every parameter is already documented, including the city default behavior, the filters id format, and the zero-based paging. The description restates the filters round-trip and the 0-based paging without adding format or constraint details beyond the schema, which is the baseline-3 case.

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?

States a specific verb and resource ('Search a marketplace for products by text and/or filters') and immediately characterizes the result set, so an agent can distinguish it from the single-item siblings (get_product, get_product_reviews, etc.). It never names an alternative explicitly, so sibling differentiation is inferred from the verb/noun 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 Guidelines3/5

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

Implied usage is present: search by text and/or filters, with facets only returned 'on request' and only on the first page. There is no explicit when-to-use/when-not guidance and no named alternative (e.g. use get_product once you have an id), so the agent must infer the workflow.

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