Skip to main content
Glama

Buscar produtos nos marketplaces

search_products
Read-only

Busca produtos por palavra-chave nas APIs dos marketplaces do bot (Shopee, AliExpress, Amazon; Kabum e Magalu quando informados em "site"). Filtre por faixa de preço (price_min/price_max) e ordene (sort: price_asc = mais barato primeiro). Cada item traz image_url, a URL da foto do produto, e price como número na moeda de "currency" (ex.: 274.99). Paginação: a resposta traz "count" e "page"; com count igual a limit, normalmente há mais resultados na página seguinte (com filtros ativos, count menor que limit não garante o fim do catálogo). Na busca multi-site, os marketplaces que falharam aparecem em "sites_failed"; a falha não quer dizer que o produto não exista neles.

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
pageNoPágina de resultados (padrão 1) — use para ver mais itens.
siteNoMarketplace a consultar. Se omitido, busca em Shopee/AliExpress/Amazon (com conversor ativo — veja get_bot_info) e junta os resultados (cada item traz "site"). "kabum" e "magalu" são opt-in: só buscam quando informados explicitamente (link de afiliado gerado via conversor ativo do bot).
sortNoOrdenação: relevance (padrão), price_asc (mais barato), price_desc (mais caro), commission_desc (maior comissão de afiliado), sales_desc (mais vendidos), rating_desc (melhor avaliados), discount_desc (maior desconto).
limitNoMáximo de resultados (1 a 50; padrão 20).
queryYesPalavra-chave / título a buscar.
price_maxNoPreço máximo (na moeda do site, geralmente BRL).
price_minNoPreço mínimo (na moeda do site, geralmente BRL).
site_filtersNoFiltros ESPECÍFICOS do marketplace (use só com "site" fixado). Shopee: { isKeySeller: bool }. AliExpress: { category_ids: "100,200", ship_to_country: "BR", delivery_days: "7" }. Amazon: { searchIndex: "Computers", condition: "New", brand: "Sony", deliveryFlags: ["Prime"], minReviewsRating: 4, minSavingPercent: 20 }.
official_onlyNoSe true, retorna só lojas oficiais (Shopee Mall / AliExpress TMALL). Onde o site não informa, o item é mantido.
commission_minNoComissão mínima, em fração (0.05 = 5%). Filtra produtos que pagam pelo menos essa comissão de afiliado. Shopee e AliExpress retornam comissão; Amazon não.
key_seller_onlyNoSe true, filtra apenas "key sellers" da Shopee — vendedores de alto desempenho selecionados pela própria plataforma. Eles têm menos probabilidade de estar em férias ou com estoque inativo. Use quando a busca retornar muitos produtos de vendedores indisponíveis. Shopee: filtro nativo (isKeySeller). Outros sites: ignorado.

Output Schema

NameRequiredDescriptionDefault
pageNo
countNo
itemsNoProdutos: title, price (número), currency, image_url, affiliate_url, site.
successNo
sites_failedNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the read-only/open-world annotations: it discloses that count == limit usually means another page but count < limit does not guarantee the end when filters are active, that failures appear in "sites_failed" and do not imply the product is absent, that commission is unavailable on Amazon, and that price is a numeric value in the "currency" unit. These are exactly the quirks that change agent behavior.

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-loads what is searched and where, then layers filtering, return shape and pagination caveats in a logical order. It is dense but nearly every sentence carries operational meaning; the image_url explanation is the only clearly low-value clause.

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 an 11-parameter multi-site search with an output schema, the description closes the gaps that matter: which sites are searched by default, how pagination actually behaves with filters, and how partial site failures should be interpreted. Nothing an agent needs to call or interpret it correctly is missing.

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 adds real value on top by glossing sort (price_asc = cheapest first), the price format (274.99 in the site currency), and the cross-parameter paging relationship between count, limit and active filters. It does not enrich the many remaining parameters (official_only, site_filters, commission_min) beyond the schema.

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 ("Busca produtos por palavra-chave") plus the concrete scope (Shopee/AliExpress/Amazon by default, Kabum/Magalu opt-in via "site"). An agent can immediately tell this is the keyword search entry point rather than a single-item lookup, though no sibling tool (e.g. get_product) is named explicitly.

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?

Gives actionable conditional rules: "site_filters" only when "site" is fixed, "key_seller_only" when many results come from unavailable sellers, and the count-vs-limit heuristic for paging. It lacks an explicit when-not/alternative-tool clause (e.g. versus get_product or convert_links), so it stops short of 5.

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