MCP tools reference

lookup_product

Resolve any identifier into a product summary with per-retailer Bucket-1 facts and computed marketplace fees.

Inputs:
  identifier: string  # required. UPC, EAN, ISBN, GTIN, ASIN, item_id, or Best Buy SKU / product id
  identifier_type?: "UPC" | "EAN" | "ISBN" | "GTIN" | "ASIN" | "item_id"
  include_cross_retailer?: boolean   # +2 tokens — cached cells for all retailers we have for this UPC (read-only)
  include_seller_context?: boolean   # +3 tokens — live restriction + WFS state
  retailer?: string                  # anchor response to a specific retailer
  force_refresh?: boolean            # bypass cache, force fresh scrape; use with retailer. Without it, accepted only for a Walmart item_id or walmart.com URL, or a product URL from another store; an Amazon /dp/ URL, ASIN or barcode needs retailer.
                                     # Sent as given: the API answers 400 when it cannot tell which retailer to refresh.

Returns:
  {
    item_id, title, brand, image, current_price,
    buybox_price,
    offers_count,                     # the API's own count, also on a base call with no offer rows
    total_offers,                     # true seller count; null when unknown
    queried_identifier,
    upc?, ean?, isbn?, gtin?, asin?, mpn?, model?,
    in_stock?, condition?, description?, msrp?, categories?,
    weight_lbs?, weight_assembled_lbs?, weight_package_lbs?,
    dimensions?, dimensions_assembled?, dimensions_package?,   # { height_in, width_in, length_in }
    sold_tag?, estimated_sales?, is_best_seller?, pack_count?, hazmat?,   # Bucket-1, Walmart, FREE in base call
    referral_fee_usd?, wfs_fee_usd?,  # computed fees, Walmart, FREE in base call
                                      # each fact appears only when the source carries it; null = no value held
    retailer_links?: [...],
    cross_retailer?: {                # only when include_cross_retailer=true
      walmart: {
        retailer, status, price, url, in_stock, unavailable,
        sold_tag, estimated_sales, is_best_seller, pack_count, hazmat,
        seller_context: {
          referral_fee_usd,   # FREE in base call
          wfs_fee_usd,        # FREE in base call
          restricted?,        # only with include_seller_context; reason is our generic message or null
          wfs_eligibility?    # only with include_seller_context; reason is our generic message or null
        }
      },
      amazon: { ... },
      ebay: { ... }, ...
    },
    seller_context?: {        # top-level, only with include_seller_context
      restricted: { any, retailers: [...], primary_reason } # Walmart reason is our generic message or null
    }
  }

Cost: 1-11 tokens depending on flags (1 base + optional +5 offers/reviews + optional +2 cross-retailer + optional +3 seller-context). The cross_retailer block is served from our cache, and when fewer than three stores hold an answer the call also reads the missing stores itself; each cell's read says whether that store was read now, earlier, or not at all and why. To force a fresh scrape of a specific retailer, call with retailer=<slug> and force_refresh=true. Each API request has a 75-second deadline; a call that runs out returns request_timeout and a dropped connection returns transport_error. Neither means the product was not found, and the server does not retry on its own.

get_offers

Current Walmart marketplace sellers for an item_id.

Inputs:
  item_id: string

Returns:
  {
    item_id,
    offer_count,
    total_offers,
    offers: [{ seller_id, seller_id_hex, seller_name, price, is_buy_box, in_stock, wfs, pro_seller, shipping_cost, delivery_date, seller_type, offer_id, max_delivery_date, max_order_quantity, fulfillment_type, returnable, return_window_days, free_returns, condition, quantity_available }],
    buy_box_seller_id
  }

Cost: 6 tokens (1 base lookup + 5 offers/reviews bundle).