Top Keywords In My Category

Top Keywords In My Category

This skill returns the top trending search keywords for one Mercado Livre (Brasil) category — the ranked list of terms shoppers are actually searching, each with its position and how many products already compete for it. It tells a seller what to put in titles and ads and where demand is concentrated.

Unlike most JoomPulse skills, the data here is real search-trend data, not an estimate. For a category's market size and opportunity index, use the category-opportunity-index skill. For the sellers ranked inside a category, use the top-sellers-in-category skill.

Prerequisites

• JoomPulse MCP access is configured for the current agent environment.
• The user names a category (free text is fine).
• The available JoomPulse tools can resolve a category and return its trending search keywords with each keyword's rank and competing-product count.

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

Scope

• Mercado Livre (Brasil) only. JoomPulse also covers Shopee Brasil, but Shopee has no search-keyword or search-demand data at all, so this analysis exists only for Mercado Livre. Never answer a Shopee keyword question with Mercado Livre terms, and never substitute a count of competing items for search demand — that measures supply, not what shoppers type.
• Real data, not an estimate. The keywords, ranks, and competing-product counts come from Mercado Livre search trends — say so; do not add the sales estimate disclaimer that other skills use.
• Read-only. The skill never writes or modifies anything.
• Language: detect the seller's language and respond in it. Default to pt-BR.
• Keep the workflow invisible. Show — for any missing value; never fabricate.

Workflow

Step 1 — Resolve the category

Ask for a category if none was given, then use JoomPulse to match the free text to a category, disambiguating with the seller when several plausible matches return.

Step 2 — Get the trending keywords

Use JoomPulse to retrieve the category's trending search keywords, each with its rank and its competing-product count. Sort by rank, best position first.

Output

Respond in the seller's language (default pt-BR). The keywords always render as a markdown table, sorted by position. The headers below are the pt-BR default and may be rendered in the seller's language:

• Posição — the keyword's rank in the category's search trends.
• Produtos (oferta) — the number of active offers (listings) matching that keyword, i.e. how many products currently compete for it. This is a real search-trend count, not an estimate.

Close with a short, optional takeaway (use the top terms in titles and ads; a high competing-product count means a crowded term, a low one a more open opportunity).

This is real Mercado Livre search-trend data, not an estimate — state that once, in place of the estimate disclaimer.

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:

• Three cards: number of keywords, the number-one term, and the least-disputed term (the one with the fewest competing products among the top).
• A horizontal bar of the top ~15 keywords (in rank order) showing the competing-product count per term, so the most-searched terms and how crowded each is are visible at a glance. Optionally flag low-competition (opportunity) terms. Render the chart only when there are enough keywords (skip under about five).

Notes & Guardrails

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

• No keywords for the category: say plainly that no trending terms were found and suggest a broader or adjacent category.
• The seller asks about Shopee: say plainly that search-keyword data does not exist for Shopee, so there is nothing to rank — do not improvise a substitute. Offer the nearest real alternative instead: Shopee category analytics, or the best-selling items in the Shopee category by estimated recent sales. If it is unclear which marketplace they mean (an identifier beginning MLB is Mercado Livre, a bare 10–11 digit number is Shopee), ask before answering.
• Data temporarily unavailable: retry once quietly; if it is still down, say the data is temporarily unavailable and to try again. Never paste internal error text, HTTP codes, or field names to the seller.