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. Other marketplaces are out of scope.
• 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 | Palavra-chave | Produtos (oferta) | |--:|---|--:|

• 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

When the client can render inline visuals, present metric cards and a chart; otherwise fall back to the markdown table plus text cards. Never block on visuals. The keywords table always renders as markdown, on every surface.

When inline visuals are available:

• 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).

Presentation rules: render a chart only when the data supports it.

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.
• 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.