Skip to main content
Glama

Supplier: Search by Keyword or Image

search_supplier_products
Read-onlyIdempotent

[Supply Product] [What it does] Searches supplier products by keyword or image across the account's visible supplier platforms, returning comparable candidates and echoing the filters that actually took effect. [When to use] Use it when the merchant wants to find products to sell, compare suppliers, or match an uploaded image; the agent also calls it first to obtain the supplier platform ID and product ID needed before a detail lookup or an import. Trigger words: sourcing, find a supplier, same as this image, best sellers, cost price. [When not to use] For variants, stock or per-country shipping on one known product use get_supplier_product and list_supplier_product_shipping_methods_and_cost; to import or map use create_pre_publish_products; for products already in the merchant's stores use list_managed_store_products. [How to use]

  • Paging depends on scope: cursor paging and a larger page size work only when one supplier platform is selected; an all-platform search returns a fixed slice per platform, so pick a platform before paging.

  • Each candidate may include supplier_product_url; Agent and 1688 Dropshipping candidates use the configured DSers product-detail page because those platforms do not expose a public supplier-site URL.

  • Compare only the metrics marked available on a candidate, and only in the base currency; unmarked metrics are unknown, and original supplier prices carry different currencies, so never infer or mix them.

  • Filters are adapted per platform: trust the echoed effective conditions and tell the merchant which filters did not apply, rather than claiming the results meet every condition.

  • If some platforms fail while others return candidates, treat it as partial coverage — report the gap and continue; do not retry the whole search or answer "nothing found". [Side effects] Read-only; never imports, edits or maps products. [Confirmation] Not required.

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_supplier_products"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoResult ordering sent to Product BFF. For one explicit supplier_platform_id, the upstream order is preserved without local re-sorting.recommended
cursorNoContinuation cursor for an explicitly selected supplier_platform_id. Invalid when supplier_platform_id is omitted.
keywordNoProduct name or keyword the user mentioned. Optional.
ship_toNoDestination country_code from prepare ship_to[], supported by all configured platforms. Defaults to US when omitted.US
image_urlNoPublicly accessible product image URL for visual search. Optional.
max_priceNoMaximum purchase price in USD major units, for example 56.78. The Tool converts it to Product BFF minor units. Supported by AliExpress, 1688 Dropshipping, and Agent.
min_priceNoMinimum purchase price in USD major units, for example 12.34. The Tool converts it to Product BFF minor units. Supported by AliExpress, 1688 Dropshipping, and Agent.
page_sizeNoMaximum candidates for an explicitly selected supplier_platform_id, up to 100. Ignored when supplier_platform_id is omitted.
ship_fromNoCountry codes from prepare ship_from[]. Supported only by AliExpress and Alibaba. Paste JSON example: ["US"].
category_idsNoCategory IDs from prepare categories[]. Supported by AliExpress, 1688 Dropshipping, and Agent. Paste JSON example: ["200003482"].
delivery_timeNoAliExpress only. Fixed preset: THREE_DAYS=Within 3 days, FIVE_DAYS=Within 5 days, SEVEN_DAYS=Within 7 days, TEN_DAYS=Within 10 days.
free_shippingNoFree-shipping checkbox value. Set to "Free" only for AliExpress, 1688 Dropshipping, or Agent; otherwise omit. This is mapped internally to Product BFF shipping_type without changing its value.
super_factoryNo1688 Dropshipping only. Set to "YES" when the user selects Super Factory; otherwise omit.
order_count_maxNoMaximum order volume, supported only by 1688 Dropshipping.
order_count_minNoMinimum order volume, supported only by 1688 Dropshipping.
shipping_methodNoExact logistics service_id copied from list_supplier_search_filters shipping_methods[]. Supported only by 1688 Dropshipping and Agent; never use the display label.
shipping_time_maxNoMaximum shipping time in days; numeric range supported only by 1688 Dropshipping and Agent.
shipping_time_minNoMinimum shipping time in days; numeric range supported only by 1688 Dropshipping and Agent.
supplier_platform_idNoSupplier platform application ID returned by list_supplier_search_filters platforms[].supplier_platform_id. Use filter values and supported_filters from that same platform. Omit to search every visible platform with per-platform filter adaptation.

Output Schema

NameRequiredDescriptionDefault
candidatesYesComparable supplier product cards
conditionsYesEffective search and filter conditions
paginationYesCursor pagination information
toolcall_response_atYesUTC timestamp when the Tool response was returned, formatted as RFC3339.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds behavior beyond them: paging only works with a single platform selected, per-platform filter adaptation means the echoed conditions may differ from what was requested, and partial platform failure should be reported as partial coverage rather than retried.

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 bracketed section labels (What it does, When to use, When not to use, How to use, Side effects, Confirmation) making it easy to scan, and every bullet carries operational content. The bracket markup and bold tokens add some visual noise, but little text is genuinely wasted.

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 a 19-parameter, 0-required, multi-platform search tool with an output schema available, the description covers the decisions an agent must make: platform selection before paging, per-platform filter support, currency caveats, partial-failure handling, and confirmation not required. Nothing essential for correct invocation appears 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, but the description adds real semantics: paging parameters (cursor, page_size) are only meaningful when supplier_platform_id is set, and metrics/prices must be compared only when marked available and never mixed across currencies. It does not walk through the platform-specific filter subsets, which the schema largely handles.

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?

States a specific verb and resource ('Searches supplier products by keyword or image') plus scope ('across the account's visible supplier platforms') and output intent ('returning comparable candidates and echoing the filters that actually took effect'). It is clearly separable from sibling lookups like get_supplier_product and list_managed_store_products.

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

Usage Guidelines5/5

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

Has an explicit 'When to use' block with concrete triggers (sourcing, find a supplier, same as this image) and an explicit 'When not to use' block that routes the agent to named alternatives: get_supplier_product and list_supplier_product_shipping_methods_and_cost for detail/shipping, create_pre_publish_products for import, list_managed_store_products for owned products.

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.