ExtensionDash: Store Rankings

View saved version →

---
name: manage-tracking
description: Use when the user wants to see or change what ExtensionDash tracks for one of their extensions, such as adding or removing tracked keywords (search terms) or competitor listings, or showing the current tracking setup. Requires an ExtensionDash account connection. Uses list_extensions, list_keywords, list_competitors, search_catalog, add_keyword, remove_keyword, add_competitor, remove_competitor and list_scrape_runs.
---

# Manage tracking

Show and change the keywords and competitors tracked for one of the user's
extensions.

## What the server supports

There are exactly four write tools: `add_keyword`, `remove_keyword`,
`add_competitor` and `remove_competitor`. Everything else is read-only.

Nothing here can:

- add or remove a tracked extension of the user's own;
- change plans, notes or settings;
- delete recorded history.

If the user asks for one of those, say it is done on the dashboard at
https://extensiondash.com. Do not attempt a workaround.

These tools need an account. If a call answers that "this connection has no
account", follow
[connecting an account](../review-performance/references/connecting-an-account.md).
Never ask for a token in the chat.

## Resolve before writing

1. **Extension.** Call `list_extensions` and match the user's wording to
   `name`.
   - If exactly one extension exists, use it and say which.
   - If the name is ambiguous or missing and there are several, ask.
     Never write to a guessed extension.
2. **Keyword scope.**
   - A keyword is a (term, locale) pair. `locale` defaults to `en`.
   - `add_keyword` adds the term in every store the extension is listed in;
     the response's `stores` says which.
   - `remove_keyword` removes the (term, locale) from every store.
   - If the user names a language or market ("track it in German"), pass
     that locale, such as `de` or `pt-BR`.
3. **Competitor identity.**
   - A competitor is a (store, external_id) pair. The id is Chrome's
     32-letter id or Firefox's AMO slug.
   - If the user gives a name, resolve it with `search_catalog` (one store
     per call).
   - If several listings plausibly match, show them with users and URL and
     ask.
   - Each store has its own roster, so a Chrome and a Firefox version of
     the same product are two competitors.
4. **Check what already exists.**
   - Call `list_keywords` before adding keywords. If a (term, locale) is
     already tracked, report it as already tracked instead of re-adding.
   - Call `list_competitors` before adding competitors. Skip ones already
     on the roster.
   - Terms are lowercased and whitespace-squished by the server, so compare
     normalized forms.

## Executing changes

- **Clear requests.** When the request names the extension (or only one
  exists) and the items, make the changes without asking for confirmation
  again.
- **Ambiguous requests.** When the target or scope is ambiguous, ask once,
  listing the specific choices.
- **Never write unasked.** Do not add a keyword or competitor the user did
  not ask for, including ideas that came up during research. Offer them;
  wait for a yes.
- **Limits.** If the server answers with a plan limit, stop for that item
  type. The message names the limit and, for competitors, the current
  roster. Report it, and ask what to remove if the user wants room. Do not
  retry.
- **Removals.** Removing a keyword or competitor stops tracking but keeps
  recorded history, and re-adding later restores it. Say so when removing.
- **Wrong-language removal.** If `remove_keyword` says the term was not
  tracked in that locale, its message lists the locales it is tracked in.
  Relay that and ask whether to remove one of them.

## After adding: pending results

A newly added item has no result when the add returns.

- **Keywords.** `add_keyword` returns rows whose `status` is `"pending"`
  until a background rank fetch lands. Then `status` becomes `"scanned"`.
  A pending row may still show an old position from earlier tracking;
  that is not the new result.
- **Competitors.** `add_competitor` returns `status: "pending"` until the
  listing fetch lands. Then it becomes `"scraped"`.

Polling rule:

- Check at most 3 times, roughly 20–30 seconds apart, using
  `list_keywords` or `list_competitors` for the same `extension_id`.
- Between checks, `list_scrape_runs` with `extension_id` shows whether the
  fetch is running, succeeded or failed.
- If it is still pending after that, stop. Tell the user the fetch is
  queued and they can check later with the same request. Do not keep
  polling, and do not promise a time.
- If `list_scrape_runs` shows a failure for the item, report it as a failed
  fetch with its `error_message`, not as a ranking. Do not promise when it
  will succeed.

## Showing the current setup

For "show my tracking", give a table per extension built from `list_keywords`
and `list_competitors`:

- **Keywords:** term, locale, store, status, position with `depth_scanned`.
- **Competitors:** name, store, users, rating, status.
- The plan limit from `list_competitors`' `limit_per_store` (null means no
  limit).
- Any pending or failed items.

## Report

End every change with a short ledger:

- **Added:** each item and the stores it landed in.
- **Already tracked:** skipped, no change.
- **Removed:** each item.
- **Failed:** the item and the server's reason, for example a limit.
- **Pending:** what is still fetching and how the user can check later.

View saved version →

---
name: research-extensions
description: Use when the user wants to research a browser-extension niche, find or compare Chrome Web Store extensions or Firefox add-ons, look for market gaps (many users but weak ratings, stale listings, few languages), read a competitor's listing, or brainstorm keywords to investigate. Works without an ExtensionDash account. Uses the ExtensionDash MCP tools search_catalog and get_listing.
---

# Research extensions

Answer market and competitor questions from the ExtensionDash catalog. The
catalog holds a weekly-refreshed copy of Chrome Web Store and Firefox Add-ons
listings, so reading it never fetches the store and never waits.

## Tools

- `search_catalog`: search one store per call. Chrome is the default; pass
  `store: "firefox"` for Firefox.
  - `query`: name words, at most 8. Use `match` (`all` or `any`) to say how
    they combine. Prefix a word with `-` to exclude it.
  - `category`: one category slug of that store.
  - Inclusive ranges: `users_min`/`users_max`, `rating_min`/`rating_max`,
    `reviews_min`/`reviews_max`, `langs_min`/`langs_max`,
    `description_length_min`/`description_length_max`, and
    `screenshots_min`/`screenshots_max`.
  - Sorting: `sort` takes users, rating, reviews, langs, description_length,
    screenshots, updated or added. `dir` is desc or asc.
  - Paging: `limit` (50 at most) and `page`.
- `get_listing`: one listing in full, given `store` and `external_id` (a
  search_catalog row's `id`). Returns the description, users, rating,
  reviews, version, languages, categories, permissions, publisher and
  `refreshed_at`.

No other tool does research. There is no live store search, no store-ranking
lookup for untracked terms, and no search-volume lookup.

## Workflow

1. **Pin down the store.** Default to Chrome. Run Firefox as a separate
   search when the user asks for it, or when the niche plainly matters there.
   Never merge the two stores into one ranking: Chrome users are a rounded
   weekly count, Firefox users an exact daily average.
2. **Resolve names to ids before comparing.** Search by the name the user
   gave.
   - An exact name match comes first unless you pass `sort`.
   - If several rows plausibly match (same or near-same name, different
     publishers or very different user counts), list the candidates with
     their user counts and URLs and ask which one is meant. Do not guess.
   - If nothing matches, say so and try fewer or alternative name words
     before concluding the catalog lacks the extension.
3. **Search the niche.** Describe the niche in name words and run a few
   searches with synonyms (`match: "any"` widens). Pass `sort: "users"` when
   you want the biggest players rather than exact-name matches.
   - Use `category` when the niche maps to one. An unknown slug is refused,
     and the refusal lists the valid slugs.
   - Name words only match names. An extension whose name never uses the
     user's words will not appear, so say the search is name-based.
4. **Filter for opportunity questions.** Translate the question into ranges.
   For example, "many users but weak ratings" becomes `users_min: 10000,
   rating_max: 3.9, reviews_min: 20`. Require a minimum review count so a
   single review does not decide a "weak rating", and state the thresholds
   you picked.
5. **Read the listings that matter** with `get_listing`, usually 2–5 of
   them. Compare promise (summary and description), permissions, languages,
   last update, publisher and the users/rating/reviews figures.
6. **Report** in the format below.

## Reading the data honestly

- **Coverage.** Every search_catalog answer carries `listed`, `known` and
  `synced_on`. Quote them, for example "the Chrome catalog holds 303,293
  listed extensions as of 2026-10-17". Results cover the catalog, not
  necessarily the whole store. `total` counts matches in the catalog only.
- **Nulls.** A null `users`, `rating` or `reviews` means the store showed no
  number. It is not zero; never average it in as zero.
- **Rounding.** Chrome user counts are rounded store figures (1,000, 2,000,
  10,000, ...). Treat two listings at "10,000" as tied, and do not read
  precision into the difference between 1,000 and 2,000.
- **Freshness.** Listing copy is English and refreshed weekly. Quote
  `refreshed_at` or `last_updated_on` when it matters.
- **Facts vs hypotheses.** Label everything inferred, such as "probably
  ranks well because its title contains the term" or "likely abandoned,
  last updated 2021", as a hypothesis. Never invent search volume, revenue,
  installs-per-day, conversion rates or causes.
- **Keyword ideas are suggestions.** Terms you pull from competitors' names
  and summaries are candidates to investigate, not proven demand. Say that
  ranking and volume data only exist once a term is tracked (see the
  manage-tracking skill), and that the catalog has no store-position data
  for terms nobody tracks.
- **Reading is not tracking.** Never imply that searching or reading a
  listing adds it to the user's account. Do not call `add_competitor` or
  `add_keyword` from this skill. Offer it as a next step instead.

## Limits and account errors

- `search_catalog` and `get_listing` allow about 60 calls a minute, with or
  without an account. Budget calls; do not page through hundreds of results.
- If a call reports a per-minute limit, stop and tell the user. Do not retry in a loop.
- Rows carry `yours` and `competitor` flags only when the connection has an
  account.

## Output

Keep it concise:

1. **Answer.** The short answer to the question.
2. **Comparison table.** Name (linked to its store `url`), store, users,
   rating (with review count), languages, last update, and one notable
   observation each.
3. **Evidence.** What you searched (store, words, filters, sort) and the
   coverage figures.
4. **Limitations.** Name-based matching, catalog coverage, rounding, nulls,
   and anything that could not be resolved.
5. **Next steps.** Concrete and optional. For example: read a specific
   listing, add a listing as a competitor, or track a candidate term to get
   real rankings. Ask before doing anything that writes to the account.

View saved version →

---
name: review-performance
description: Use when the user asks how their own tracked browser extension is doing on ExtensionDash, such as users, ratings, keyword positions over a period, which keywords improved or dropped, which competitors are overtaking them, or what to investigate first. Requires an ExtensionDash account connection. Uses list_extensions, get_extension, get_metrics_history, list_keywords, get_keyword_ranks, list_competitors, get_keyword_serp and list_scrape_runs.
---

# Review performance

Explain how the user's tracked extensions moved, using only what ExtensionDash
has recorded. Every tool used here is read-only.

## Prerequisite: an account connection

These tools need an account. If a call answers that "this connection has no
account", stop and follow [connecting an account](references/connecting-an-account.md).
Never ask the user to paste a token into the chat.

## Workflow

1. **Resolve the extension.** Call `list_extensions`. Use its `id` as
   `extension_id` everywhere else.
   - If the user named an extension, match it against `name`. If more than
     one matches, or none does, list what exists and ask.
   - If the user has exactly one extension, use it and say so.
   - `list_extensions` also gives each listing's latest `users_count`,
     `users_rounded`, `users_delta_7d`, `rating_average`, `ratings_count`
     and `last_scraped_at`. That is enough for "how is it doing right now".
2. **Fix the comparison period.** Use the user's period if they gave one,
   or 7 days by default. State the exact dates.
   - `improvement_7d` and `users_delta_7d` are fixed 7-day comparisons.
   - For any other period, pass `days` to the history tools and compare
     the first and last observed dates yourself.
3. **Users and ratings.** Call `get_metrics_history` with `days` (and
   `store` when one store is in question). Each metric is a map of ISO
   date to value.
   - Compare the earliest and latest dates actually present, and name
     them. An empty map means nothing was measured in range. It is not
     zero.
   - If `users_rounded_in_range` is true, the store published rounded
     counts, so small moves may be rounding.
   - With `include_competitors: true` or a `competitors` list, rivals'
     series arrive too. Competitors are sampled every few days, so compare
     them against the user's numbers on dates present in both, never by
     position in the map.
4. **Keyword positions.** Call `list_keywords` for the current state, and
   `get_keyword_ranks` with `days` for movement over the period. Narrow
   with `term`, `store` or `locale` as needed.
5. **Competition.**
   - Call `list_competitors` with `include_observed: true`.
     - `competitors` is the roster the user tracks.
     - `candidates` are other listings seen in the user's recorded
       results, ranked by how often they beat the user.
     - Use `ahead_of_us_on`, `terms_seen`, `terms_tracked`,
       `average_position` and `best_position` as the evidence for
       "who is overtaking me".
   - For one term, call `get_keyword_serp` with `store`, `term` and
     `locale`. It returns the recorded page with `mine`/`competitor` flags
     and `moved_up_by`. Pass `window: true` for just the leaders and the
     user's neighbourhood.
6. **Separate collection problems from performance.** If numbers are
   missing, stale, or a term looks stuck, call `list_scrape_runs` with
   `extension_id` (and `status: "failure"` if useful).
   - A failed fetch is a data-collection problem, not a ranking drop.
     Report it separately.
   - `expected_failure: true`, for example a delisted listing, is not
     signal.
7. **Report** in the format below.

## Reading rankings correctly

Each keyword row and rank point is one (term, store, locale) result. Keep
stores and locales apart. "ad blocker" in Chrome/en, Firefox/en and
Chrome/de are three separate results; never average them.

Keyword rows fall into three states. Keep them distinct:

| State | How it looks | Say |
| --- | --- | --- |
| Never scanned | `status: "pending"`, no `captured_on` | "No result yet; the first fetch has not landed." |
| Scanned and found | `position` is a number | "#7 of the 50 results scanned on 2026-10-17." |
| Scanned but absent | `status: "scanned"`, `position: null` | "Not in the top 13 results scanned." |

Rules for positions:

- **Always give the depth.** Report every position with `depth_scanned`,
  because #1 of 6 and #1 of 50 are different results.
- **Shallow scans.** `shallow: true` means the store returned fewer results
  than the usual scan depth.
- **Absent is not a rank.** Never turn "not found within N" into a rank
  such as N+1 or 51.
- **Stale positions.** A `pending` row may still carry an old position from
  earlier tracking. Check `captured_on` before quoting it.
- **Direction of movement.**
  - `improvement_7d` and `moved_up_by` are positive when the extension
    moved up the page.
  - `improvement_7d` is null when there is no 7-day baseline, or when the
    extension is absent now. Call that "insufficient history", not "no
    change".
- **Search volume.** `search_volume` is Google web-search demand (Google
  Ads), not searches inside the store. It is the same for both stores.
  Null means unknown, not zero.

## Reading user counts correctly

- **Units differ by store.** Chrome users are a rounded store figure.
  Firefox users are AMO's daily-average users. Never add them together,
  rank them against each other, or call them equivalent.
- **Rounding.** `users_rounded: true` means the store rounded the number.
  A move across a rounding boundary (for example 9,000 to 10,000) is not a
  measured gain of 1,000.
- **Rating precision.** Ratings come with their review counts. A 5.0 from
  one review is not evidence of quality.

## Causation

Report what changed and when. Listing edits, new keywords, or a competitor's
update may coincide with a move. Present those as hypotheses to check, never
as the cause, unless the data directly shows it.

## Output

1. **Period.** Exact dates, the stores and locales covered.
2. **Key changes.** The 3–6 biggest movements: users, ratings and keyword
   positions (with depth), each with its numbers.
3. **Competition.** Who is ahead of the user on the most terms, with the
   evidence fields.
4. **Data limitations.** Missing baselines, pending terms, shallow scans,
   rounded counts, failed fetches.
5. **What to investigate first.** A prioritized list of 2–4 concrete
   checks, each tied to evidence above. Suggest tracking changes as an
   offer, never as an action already taken.

Referenced files: 1 — file references are metadata, not package contents.