Category Monitor

Category Monitor

This skill tracks one category's aggregate health over time on Mercado Livre (Brasil) or Shopee Brasil — its estimated sales, how many products and sellers it holds, how those sellers split across tiers, and how concentrated the market is.

Each run builds today's snapshot table for the category and offers it as a downloadable table. To see what changed, the user supplies the table from a previous period (the one this skill produced before); the skill compares the two and shows the difference per metric. The baseline is whatever table the user provides — there is no hidden session memory and nothing is stored server-side. The default view is the whole category; on Mercado Livre the user may instead point it at a single listing or a catalog product (a catalog product rolls up its competing listings). Shopee has no catalogue at all, so that input mode does not exist there.

To track one named product over time, use the product-change-monitor skill. For a one-shot opportunity / market-size snapshot, use the category-opportunity-index skill.

Prerequisites

• JoomPulse MCP access is configured for the current agent environment.
• The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and names a category (on Mercado Livre, optionally a single listing or a catalog product instead).
• For a period comparison, the user supplies a previous table that this skill produced for the same category on the same marketplace (pasted or uploaded). Without it, the skill produces a standalone snapshot.
• The available JoomPulse tools can resolve a category name to its identifier and return that category's monthly aggregate metrics and its seller-tier breakdown on either marketplace.

If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can monitor a category.

Scope

• Mercado Livre (Brasil) and Shopee Brasil, one at a time. Other marketplaces are out of scope.
• Sales and revenue are JoomPulse estimates — not real transactions. Disclose this in every output. The estimates are built differently on each marketplace: on Mercado Livre from historical listing data, on Shopee from the marketplace's own rounded sold counters refined with review movement. Use the matching disclaimer.
• Read-only. The skill never writes or modifies anything; it does not store the snapshot — the user keeps the downloadable table and brings it back next period.
• Language: detect the seller's language and respond in it. Default to pt-BR.
• The baseline is user-supplied. Never claim a change without a previous table to compare against, and never infer or fabricate one from memory.

Shopee data — what differs from Mercado Livre

• Estimates come from Shopee's own rounded sold counters, refined with review movement. Treat small gaps between items as noise and never rank on a difference of a few units. Price, rating and review count are real.
• Coverage is not a census: only items with at least one lifetime sale are tracked, so any count is a lower bound and an absent item is not evidence it does not sell.
• History starts May 2026 — there is no long-run trend and no seasonal read.
• Category analytics stop at three levels; the item view reaches deeper. Say which you used.
• No seller medals — Shopee has three mutually exclusive shop tiers: Official store, Preferred (Indicado) and Common. There is no ladder; inventing Shopee medals is fabrication.
• No catalogue and no buy-box, and an item belongs to one shop.
• No fulfilment programme, no free-shipping flag and no listing tier — show — rather than guessing.
• Concentration is measured differently and thresholds do not transfer between marketplaces.
• Item titles mix Portuguese, English and Chinese — search both languages.

Workflow

Step 0 — Decide the marketplace

JoomPulse covers two separate marketplaces: Mercado Livre (Brasil) and Shopee Brasil. They are independent datasets with different coverage, history and mechanics. Decide which one the request belongs to before reading any data:

• The seller said so. "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" means Mercado Livre.
• An identifier gives it away. An identifier beginning MLB is Mercado Livre; a bare 10–11 digit number is a Shopee item or shop. A mercadolivre.com.br link is Mercado Livre, a shopee.com.br link is Shopee. If an identifier is not found on the marketplace you assumed, check the other one before telling the seller it does not exist.
• The request only makes sense on one of them — buy-box, catalogue position, seller medals, a fulfilment programme or search keywords are Mercado Livre only.
• Otherwise ask — one short question, mentioning that both are available. Never guess and never default.

Never mix data from the two marketplaces in one query, one table or one total. They are separate pipelines with different grains and estimate methods; a combined figure is simply wrong. If the seller wants both, run the analysis twice and report the two side by side, comparing direction and orders of magnitude — never exact numbers.

Step 1 — Resolve what to monitor

Ask for a category if none was given, then use JoomPulse to match the free text to a category on the chosen marketplace (disambiguate with the user when several plausible matches return, listing the candidates with their level). On Mercado Livre the user may instead point the skill at a single listing or a catalog product. On Shopee, category analytics stop at three levels and there is no catalogue — if the seller names a deeper niche, answer at its level-3 ancestor and say out loud which category the snapshot actually describes; a catalog product is not an available input there.

Step 2 — Collect today's aggregates

Use JoomPulse to collect, for the target:

• Mercado Livre: estimated sales, number of products, number of catalog products, number of active sellers, the seller-medal distribution, and the monopolization level.
• Shopee: estimated sales, number of products, number of sellers, the split across the three shop tiers (Official store / Preferred (Indicado) / Common), and the concentration measure. Omit the catalog-products metric entirely — Shopee has no catalogue, so drop that row rather than leaving it blank. There are no medals and no ladder either: report the three-tier breakdown, never a four-tier medal one.

Two Shopee-specific cautions:

• The flag that marks a month as the latest is unreliable. Resolve the most recent available month explicitly instead of trusting it, and state in the output which month the snapshot describes.
• Concentration is a different measurement on the two marketplaces. On Mercado Livre it is the leading seller's share (monopolization); on Shopee it is an index computed across all sellers. Label it with the term that belongs to the marketplace you queried, and never compare the two marketplaces' values.

Step 3 — Present today's snapshot and offer it for download

Render the snapshot table for today, headed with the marketplace, the category name and the date — and, on Shopee, the month the aggregates cover. This table is the deliverable — and offer it as a downloadable file (.csv / .xlsx) so the user can save it and bring it back next period as the baseline. On a standalone snapshot there is no change column and no color-dot legend — just metric and current value.

Step 4 — Offer comparison, and compare if a previous table is supplied

Invite the user to send a previous table for the same category on the same marketplace to compare periods. If they provide one, parse its metric values, align by metric to today's snapshot, and render a comparison table with the difference per metric. A difference requires both an old and a new value for the same metric — if a metric is missing or unreadable in the supplied table, show —, never a fabricated trend. If no previous table is supplied, the snapshot stands on its own and the user is told to save it for next time.

On Shopee the comparison is also limited by the data itself: history starts May 2026 and partial months are excluded, so a prior period may simply not exist yet. Say that plainly instead of inventing a baseline or comparing against an incomplete month.

Output

Respond in the seller's language (default pt-BR). Name the marketplace the figures came from.

Snapshot (always): a markdown table | Métrica | Valor atual |, plus a downloadable .csv / .xlsx of the same data.

• Mercado Livre rows: Vendas (estimadas), Produtos, Produtos de catálogo, Vendedores, Distribuição de medalhas, Monopolização.
• Shopee rows: Vendas (estimadas), Produtos, Vendedores, Distribuição por tipo de loja, Concentração — there is no Produtos de catálogo row; omit it rather than showing it empty.

Comparison (only when a previous table is supplied): a markdown table | Métrica | Anterior | Atual |. Put the change (figure or percentage point) inside the Atual cell, prefixed with a semantic color dot:

• Vendas ↑ = 🟢; Vendas ↓ = 🔴.
• Monopolização (Mercado Livre) and Concentração (Shopee) are inverted (like cancellation rate): down = 🟢 (easier to enter), up = 🔴. The direction rule holds on both marketplaces even though the measurements differ.
• Produtos / Vendedores moving is neutral context — show the change without a strong good/bad dot.
• Distribuição de medalhas (Mercado Livre) — show the tiers that moved (for example platina 4 → 5). On Shopee the same line is the shop-tier breakdown: show which of the three tiers moved (for example Indicado 12 → 15), and never phrase it as a medal or a rung.

Column headers are words (Métrica | Anterior | Atual), never a bare "Δ" symbol. Show the color-dot legend (🟢/🔴) only in the comparison table, where the dots actually appear — never on a plain snapshot.

Close with a short Principais insights section: with a comparison, interpret what moved; on a standalone snapshot, frame it as the starting picture with no trend claims.

Disclaimer (every report) — use the variant for the marketplace you queried.

Mercado Livre:

⚠️ Vendas, vendedores, produtos e monopolização são estimativas do JoomPulse com base no histórico de anúncios — não são transações reais. / Sales, sellers, products, and monopolization are JoomPulse estimates based on historical listing data — not actual transactions.

Shopee:

⚠️ Vendas são estimativas do JoomPulse a partir dos contadores arredondados da própria Shopee — não são transações reais. Só itens com pelo menos uma venda no histórico são rastreados, então as contagens são um piso, e a concentração é medida de forma diferente da do Mercado Livre. / Sales are JoomPulse estimates built from Shopee's own rounded sold counters — not actual transactions. Only items with at least one lifetime sale are tracked, so the counts are a lower bound, and concentration is measured differently than on Mercado Livre.

Visualization

Render the visuals every time the data supports them. As soon as the analysis is done, present the cards and charts described below as a self-contained visual panel — an artifact where the client renders artifacts, an inline widget where it renders widgets. Do not ask permission first, do not describe the panel instead of drawing it, and do not offer it as an optional extra: the cards and charts are part of the answer, not a follow-up.

• Order: the cards first, then the charts, then the written read.
• The data table always stays markdown in the response text, never inside the panel — the panel carries cards and charts only.
• The estimate disclaimer always stays in the response text as well.
• Skip an individual chart when its own data threshold is not met (each threshold is stated below): a chart nobody can read is worse than no chart. Skipping one chart never means skipping the panel.
• Only the cards and charts specified below. Do not invent extra ones, and do not promote a categorical value to a bar — a chip or plain text is the honest rendering for it.
• If no visual surface is available at all, fall back to the markdown table plus the same figures written as text cards. Never block on visuals, and never leave the answer without its numbers.

The panel contains:

• Cards: estimated sales, number of products and number of active sellers, plus the concentration figure as a value or small bar — labelled Monopolização on Mercado Livre, Concentração on Shopee. On Mercado Livre add a number of catalog products card; on Shopee there is no such card — drop it. With a comparison, you may annotate each card with its anterior → atual change.
• A distribution bar: on Mercado Livre, sellers (or listings) split across medal tiers using the medal palette — platina = purple, ouro = amber, prata = blue, sem medalha = white with a thin border (white needs the border to stay visible on a light background). On Shopee, a three-tier bar — Official store / Preferred (Indicado) / Common — with plain labels and a neutral palette: no medal colours, no four-tier phrasing, and never a shop tier mapped onto a medal. With a previous table, note the shift.
• No synthesized trend line from a single run (there is no server-side history). Only if the user supplies several past-period tables may you plot a simple line across those periods.

Presentation rules: column headers are words, never a bare "Δ" symbol; show the color-dot legend only when those dots appear (the comparison table); and the downloadable file mirrors what is shown.

Notes & Guardrails

The seller should never see a system or stack error — only a friendly next step.

• No previous table supplied: render today's snapshot only (no change column, no legend) and invite the user to save it for next time.
• Supplied table is for a different category, a different marketplace, malformed, or unreadable: say so plainly and fall back to the snapshot only; do not force a misaligned comparison, and never align a Shopee table against a Mercado Livre one.
• No prior period available on Shopee: history starts May 2026 and partial months are excluded — say the comparison has no baseline yet instead of producing one.
• Category deeper than Shopee's third level: answer at its level-3 ancestor and state which category the numbers actually describe.
• Empty or failed data: say the data is temporarily unavailable and to try again. Never paste internal error text, HTTP codes, or field names to the seller.
• Catalog product input (Mercado Livre only): when monitoring a catalog product, note the buy-box competition (how many sellers compete) rather than implying a single listing. Shopee has neither a catalogue nor a buy-box, so this mode does not apply there.