SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-damai-mercado-market-intelligence

linkfox-damai-mercado-market-intelligence

Agents & models

View repository

Updated 10-16 00:00

About this skill

Damai Mercado Libre Market Intelligence

This skill researches Mercado Libre markets through one LinkFox gateway endpoint. It selects the appropriate operation, validates snake_case arguments, and presents category, industry, product, trend, image-search, or review data.

Core Concepts

  • Call only ${LINKFOX_TOOL_GATEWAY}/damai/call. Never call the upstream data provider directly or ask the user for an upstream X-API-Key.
  • Send {"toolName":"...","arguments":{...}}; preserve documented snake_case field names exactly.
  • Treat search_categories and get_my_quota_status as free operations. Each successful call to one of the other five operations costs 12 LinkFox points (￥0.12) and consumes one upstream plan request when an active plan exists, or one upstream point when the account is in points billing mode. Plan expiry or exhaustion does not automatically fall back to points; inspect quota status instead of guessing the billing mode.
  • Read data first. Use contentText only when data is textual or ambiguous; do not show rawResponse unless diagnostics are requested.
  • Read references/api.md before constructing uncommon filters or interpreting provider-specific fields.

Data Fields

Operation Main output
Category search Category IDs, localized paths, level, 30-day orders/GMV, price, merchant and listing counts
Industry overview Monthly order/price/GMV trends and category summary metrics
Product search Products, prices, 30/60/90-day and lifetime sales, seller/category data, fulfillment, inventory, attribute aggregation
Sales trend Monthly and ISO-week order series with coverage metadata
Image search Similar Mercado Libre product IDs and provider status
Review search Review text, rating, date, product and buyer fields

Parameter Guide

  • Markets: MLM Mexico, MLB Brazil, MLA Argentina, MLC Chile, MCO Colombia. Default is MLM when omitted.
  • Category keywords and product keywords must use the selected market's local language.
  • Resolve a category name with free search_categories before using paid category analysis.
  • search_product_snapshots requires at least one of keyword, category_id, sku_id, shop_id, shop_query, or product_url.
  • image_search_products requires image_url or image_base64. For a local image, run python scripts/upload_image.py <path> and use the returned public URL.
  • product_sales_trend.days accepts 1-731. review_search.limit and product-search limit accept at most 100.
  • Product listing dates accept YYYYMMDD or YYYY-MM-DD. Product sort fields are sales_30d, historical_total_sales, price, listing_date, rating, review_count, or title.
  • product_status accepts a string such as active/paused or an upstream integer status value.
  • Do not pass uId, uid, memberId, undocumented camelCase aliases, or unknown fields.

How to call

  • API endpoint：POST /damai/call(for complete parameters/response/error codes see references/api.md）
  • Python script：python scripts/damai_mercado_market_intelligence.py '<JSON 参数>' [--inline]
  • Cost constraints: This tool consumes compute; by default, the same parameter combination in the same session is only called once, and the script has a 24h local cache. On failure/empty results, do not automatically switch keywords, page through, or change the postal code to probe continuously; if retrieval needs to continue, first explain to the user that additional consumption will be incurred.

Output strategy (default script behavior)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-damai-mercado-market-intelligence-<timestamp>.json（<cwd> is the working directory when the script executes, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated according to the user's task;Writing to /tmp is prohibited, if the current directory is not writable, report an error)
  • Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout only outputs a summary (top-level fields, common counts such as total/costToken, and the length of the largest list field + the first 3 samples)
  • Add --inline to force full printing to stdout (also written to disk)

Data reading recommendations: first look at the summary to judge whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide resolution:

Abnormal situations

  • API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

Local Image Upload

image_search_products requires a public image URL or Base64 content. When the user provides a local image, run python scripts/upload_image.py <path> first. The helper requests ${LINKFOX_TOOL_GATEWAY}/oss/file/presignedPut, uploads the file with the returned presigned PUT URL, and prints a public URL valid for 24 hours. Pass that URL as arguments.image_url; never place the presigned query string or image Base64 in user-visible output.

Usage Examples

# Free category lookup
python scripts/damai_mercado_market_intelligence.py '{"toolName":"search_categories","arguments":{"market_code":"MLM","query":"celulares","limit":10}}'

# Product opportunity search
python scripts/damai_mercado_market_intelligence.py '{"toolName":"search_product_snapshots","arguments":{"market_code":"MLM","category_id":"MLM1055","sort_by":"sales_30d","sort_order":"desc","page":1,"limit":20}}'

# Product sales trend
python scripts/damai_mercado_market_intelligence.py '{"toolName":"product_sales_trend","arguments":{"market_code":"MLM","sku_id":"MLM1602785195","days":90}}'

Display Rules

  1. Present only fields supported by the response; do not invent demand, profit, or competition conclusions.
  2. State the market, filters, time coverage, record count, currency, and pagination when available.
  3. For category results, show the full localized path and whether the category is terminal.
  4. For product results, prioritize product ID/title, price, 30-day orders, lifetime orders, rating/reviews, seller, category, listing date, fulfillment, and inventory.
  5. For trends, distinguish requested days from covered days and surface incomplete-coverage notices.
  6. Image search returns product IDs; explain that fetching full product records requires another potentially paid operation.
  7. Preserve review language and label translations only when the upstream response provides them.

Important Limitations

  • Provider data can be delayed or incomplete; data_available=false, empty records, and coverage notices are valid business results.
  • Product-search product_status, image-search token, and some fulfillment values are provider-defined; do not invent undocumented enums.
  • A successful paid operation may consume upstream quota even when no matching business records are found.
  • Do not retry paid operations automatically after timeout, 5xx, or an ambiguous connection failure.
  • Do not expose LinkFox keys, upstream credentials, full Base64 images, or provider account identifiers.

Error handling

Scenario Handling
Parameter error or errcode=1002 Correct according to references/api.md ; if the user's filtering intent needs to be changed, ask the user first
HTTP 401/402 or insufficient LinkFox compute Use references/onboarding.md to guide and stop calling
HTTP 403 or errcode=1005 prompt to contact the backend to check routing and hosting keys; do not ask the user to provide upstream keys
Damai upstream package, compute, or quota abnormality call the free get_my_quota_status at most once as an auxiliary explanation, then stop paid calls
HTTP 429/5xx、errcode=1003 or timeout do not automatically retry; explain that the result is uncertain, and call again only after the user explicitly agrees
Success but no data Truthfully display the empty result and filter conditions; do not automatically change terms, page through, or change markets
Local image upload failed do not call the paid image search; first fix the image input or upload issue

When judging the result, also check the HTTP status,code / errcode、error / errmsg and the business data; do not rely only on the script exit code, and do not automatically retry paid operations.

User Expression & Scenario Quick Reference

Applicable -- Mercado Libre category, market, product, trend, image-similarity, and review research:

User says Action
"Find the Mexico mobile phone category" / "Mercado Libre category ID" Use search_categories
"Market size and trends for this category" Resolve category, then use industry_overview
"Filter Mercado Libre products with high monthly sales" / "Check this SKU" Use search_product_snapshots
"Recent sales trend for this product" Use product_sales_trend
"Use this image to find the same item on Mercado Libre" Use image_search_products
"Analyze the reviews for this product" Use review_search

Not applicable -- Store authorization, listing publication, inventory updates, order fulfillment, refunds, advertising operations, or other Mercado Libre official seller APIs.

Boundary judgment: Use this skill when the user needs market or product intelligence from the documented data operations. Do not use it for seller-account mutations, official commerce workflows, or unsupported predictive conclusions.

Compute power consumption rules

  • search_categories、get_my_quota_status is free and does not deduct LinkFox compute power.
  • industry_overview、search_product_snapshots、product_sales_trend、image_search_products、review_search Each successful call charges 12 LinkFox compute power (￥0.12)。

Users pay compute power for paid operations. When multiple paid operations need to be called consecutively, for high-frequency queries, or when paging, first explain the estimated number of calls and compute power consumption, and let the user decide whether to continue.

Feedback

Auto-detect and report feedback through the Feedback API in references/api.md when the skill behavior, documentation, or result presentation mismatches the user's intent, or when the user expresses praise or dissatisfaction. Never include credentials, private data, Base64 images, or complete large responses.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.