Skip to main content
Glama
Procurement MCP

Procurement MCP

by belikh

search_offers

Search multiple Chinese and Australian marketplaces at once for a product and get ranked, landed-cost offers with shipping estimates, plus past sale prices and per-marketplace diagnostics.

Instructions

Search marketplaces for a product and return ranked offers.

The result lists buyable offers first (kind='offer', ranked by `sort`), then
past sale prices (kind='comp'), then one kind='diagnostic' entry for every
requested marketplace that returned no offers. A diagnostic's
diagnostic_code is one of: missing_key, timeout, upstream_error, quota,
unsupported, degraded, unsubscribed, no_results.

Each offer has shipping.delivery (direct, pickup, via_forwarder or unknown)
for the destination postcode and landed_aud, the total for `qty` delivered.
landed_basis says how firm that total is: exact, estimated (China offers,
from a forwarder rate and an assumed weight) or item_only (shipping cost not
stated). Offers that cannot reach the destination are left out and counted
in a not_deliverable diagnostic.

All marketplaces run at once under one deadline. Hosted scraper sources
take 30 to 90 s, so a short deadline reports them as timeout.

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

Input Schema

NameRequiredDescriptionDefault
qtyNoRequested quantity. Offers with a larger minimum order rank last.
sortNoRanking intentbest_value
queryYesProduct keyword, e.g. 'wireless mouse'. Sent as written to every source.
ship_toNoDestination country code. Default: SHIP_TO_COUNTRY (AU).
postcodeNoDestination postcode. Default: SHIP_TO_POSTCODE (4000, Brisbane).
query_zhNoThe query in Chinese, e.g. 硅胶厨具. Used for taobao, tmall, 1688 and jd, which match Chinese far better than English. Translate the query yourself and pass it here.
deadline_sNoSeconds allowed for the whole search. Default: PROCUREMENT_DEADLINE_S.
max_resultsNoPer-marketplace cap, then ranked globally
marketplacesNoSubset to search. Defaults to all. Valid: taobao, tmall, 1688, jd, pdd, aliexpress, ebay_au, ebay_sold (past AU sale prices, returned as kind='comp'), amazon_au, gumtree, facebook, woolworths, coles, aldi (grocery with unit pricing), ozbargain, cheapies. An unknown name returns a diagnostic entry.
ebay_auctionsNoeBay: auction listings only (current bid, bid count, end time). Default: fixed price.
est_weight_kgNoWeight of one item in kg. Used for the freight forwarder estimate on taobao, tmall, 1688, jd and pdd offers. Default: FORWARDER_DEFAULT_WEIGHT_KG.
include_pickupNoInclude listings that must be collected in person near the destination.
ebay_seller_scopeNoeBay seller scope. 'domestic': items located in AU. 'global': world-wide sellers on the AU marketplace. 'auto': eBay default ranking.domestic

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so thoroughly: it discloses the result ordering (offers, then comps, then diagnostics), the eight diagnostic codes, the landed_basis confidence levels, that undeliverable offers are silently omitted but counted, and that all marketplaces run concurrently under one deadline with 30-90 s scraper latency. That is exactly the kind of behavior an agent cannot infer from schema alone.

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?

The four short paragraphs are front-loaded and each covers a distinct concern: purpose, result composition, offer fields, and timing. Some density is unavoidable for a 13-parameter tool, though the diagnostic-code list and landed_basis enumeration are the kind of detail that could have been tightened.

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 complex 13-parameter tool with no annotations, the description supplies the operational context an agent needs: what comes back and in what order, how to interpret delivered totals, and how deadlines affect results. An output schema exists, yet the description's extra framing of result kinds is additive rather than redundant.

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 cross-parameter meaning the schema does not: `qty` determines the landed_aud total and minimum-order ranking, `sort` drives offer ranking, and `deadline_s` interacts with slow scraper sources to produce timeouts. It does not re-explain the Chinese-marketplace routing for query_zh, but the schema already covers that.

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?

The opening sentence gives a specific verb and scope: 'Search marketplaces for a product and return ranked offers.' That immediately distinguishes it from siblings like get_offer_detail (single-item lookup) and search_by_image (visual query), and the rest of the description reinforces the multi-marketplace aggregate nature.

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 only implied. The description explains mechanics that inform usage decisions (a short deadline times out hosted scrapers, unknown marketplace names produce a diagnostic), but it never states when to pick this over search_by_image or latest_deals, nor any prerequisite about API keys/configuration beyond the 'missing_key' diagnostic code.

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