AppFollow AI Toolkit

Stored ASO downloads/conversions report for App Store. Required: `ext_id`, plus at least one more argument -- `ext_id` on its own is always rejected by the upstream. In practice send `channel` (`channel` for breakdown by source, `time_series` for totals) with `from` and `to`; `country` and `period` (`daily`/`weekly`/`monthly`) narrow it further. Needs an ASO Report integration on the client; without one the call answers FEATURE_DISABLED. Costs 12 credits, also when it is refused with FEATURE_DISABLED. Read-only.

Google Data Console (GDC) ASO report for Google Play. Required: `ext_id` (a Google Play package; an App Store id answers VALIDATION_ERROR), `channel` (`all`/`search`/`explore`/`3rdparty`), `from`, `to`. Optional: `country`. Requires the GDC feature on the client; upstream feature-gate errors surface as FEATURE_DISABLED. Costs 12 credits.

Returns the current AppFollow credit balance for the user's company (client): available (monthly allowance), current (spent so far this period), remaining (= available - current, clamped at 0), is_overdraft, overdraft_value. Free (the endpoint bypasses billing). Read-only, no arguments.

Google Play **console** ratings (richer than the public scrape). Google Play only. Requires the GP-console feature + an active GP-console connection on the client: without the feature or the console connection this tool returns FEATURE_DISABLED; a specific `country` also needs the client's by-country console feature (FEATURE_DISABLED otherwise). Identity: `apps_id` (the workspace's `collectionId` in `list_collections`) + `ext_id` (the app's Google Play id, `extId` in `list_apps`); the tool first looks the app up in that workspace, and when the workspace tracks the same `ext_id` more than once the lowest `itemId` wins. Required: `apps_id`, `ext_id`, `from`, `to` (`from` must be before `to`), `fields` (`ratings` or `users`, exactly one). Options: `period` (`daily`/`weekly`/`monthly`, default `daily`), `country` (one two-letter code, or `all` for worldwide, the default). Returns `{fields: {defaultGpRating | usersCountPerDay: [{date, value}]}}`, the full series in one call: no paging. Read-only. Costs 12 credits per started 14 days of the `from`-`to` span, at least 12: 1-14 days apart 12; 15-28 days apart 24; 29-42 days apart 36. The app lookup is free.

Category and search rankings for an app on a given date. Required: `ext_id`. Optional: `country` (two-letter code), `device` (e.g. `iphone`, `ipad`), `genre_id` (store category id), `date` (defaults to yesterday, UTC). Costs 12 credits. Read-only.

Time-series public ratings for one app over a date range, for one country or worldwide. Identity: `ext_id` (the app's store id, `extId` in `list_apps`) + `store` (the short store code; `list_apps` reports the long store name, e.g. `itunes` = `as`, `googleplay` = `gp`, and its description maps every store). Required: `ext_id`, `store`, `from`, `to` (`from` must be before `to`). Options: `country` (one two-letter code, or `all` for worldwide, the default), `period` (`daily`/`weekly`/`monthly`, default `daily`), `type` (`total` cumulative, the default, or `diff` incremental -- not for `gp`), `include_negative_changes` (`diff` only, default false). Returns `{distribution: [{date, value, starsTotal, stars, version}]}`, the full series in one call: no paging. Read-only. Costs 12 credits per started 14 days of the `from`-`to` span, per country (one call per country), at least 12: 1-14 days apart 12; 15-28 days apart 24; 29-42 days apart 36.

Fetch reviews for one workspace (collection) or one app in it. Required: `apps_id` (the workspace's `collectionId` from `list_collections`), `from`, `to` (YYYY-MM-DD, `from` before `to`). Optional: `ext_id` (the app's `extId` from `list_apps`; absent = the workspace's own apps, competitor apps are left out unless named; if the workspace tracks the same `ext_id` twice, the lowest `itemId` is used), `country` (two-letter code; absent or `all` = every country), `lang` (device language code), `q` (text search), `rating` (stars to keep, e.g. `[1, 2]`), `sort` (default `default`), `limit` (1-100 reviews per page, default 100), `testing_feedback` (`true` = Google Play testing feedback instead of public reviews; requires the feature and a Google Play Console connection; use with a Google Play `ext_id`). Pagination: the response is `{reviews: [...], nextCursor}`; repeat the call with the same arguments plus `cursor` set to the previous `nextCursor`, and stop when `nextCursor` is null or absent. Each review carries `reviewId` and `metaInformation.store`, the inputs `reply_to_review` takes. Costs 12 credits per page; setting `ext_id` adds a free app lookup. Read-only.

Flat AI-generated bullet summary of an app's reviews over a window. Returns `{status, summary: [..]}`. Required: `from`, `to`, `ext_id`, `collection_name`, `store` (`as`/`gp`/`ms`/`am`); optional `countries` (array of two-letter codes). Needs the `ai_summary_public_api` feature — without it the upstream refuses the call, surfaced as FEATURE_DISABLED (plan gate) or ACCESS_DENIED. If the client has no country connected the refusal surfaces as FEATURE_DISABLED. Costs 48 credits.

Review count and average rating for one workspace (collection) or one app in it, each with the previous-period value and the change. Returns `{total: {value, previous, diff}, rating: {rating: {value, previous, diff}, starsTotal: [1-star .. 5-star counts]}}`. Call this BEFORE paging `get_reviews` to size the work; it counts public reviews only, so it does not size a `get_reviews` call with `testing_feedback: true`. Required: `apps_id` (the workspace's `collectionId` from `list_collections`). Optional: `ext_id` (the app's `extId` from `list_apps`; absent = the workspace's own apps, competitor apps are left out unless named; the same `ext_id` tracked twice uses the lowest `itemId`), `country` (absent or `all` = every country), `lang` (device language code), `from`, `to` (YYYY-MM-DD, `from` before `to`; `to` absent = today, `from` absent = 30 days before `to`). No pagination. Costs 24 credits, two 12-credit metric reads; setting `ext_id` adds a free app lookup.

Returns the server's build identity and liveness: `release` (the deployed build sha, mirrors `GET /version`; null if unset), `version` (the MCP service version, `MAJOR.MINOR.PATCH`), `toolkit` (the AppFollow AI Toolkit skills this server serves: `version`, the 8-character commit `sha` and the `sha256:` `digest` of the served files; null when it serves none) and `healthy` (always true when this call returns -- reaching an authenticated tool already proves the server is serving; mirrors the `/healthcheck` liveness leg, not full DB readiness). Free (no credit cost, no upstream call). Read-only, no arguments. Use for preflight / build-identity verification when no shell/curl is available.

[WRITE] Bulk-upload reviews from a custom source (Advanced API / Custom). Required: `reviews` (array of review objects per AppFollow's bulk upload schema), `ext_id` (a client-supplied idempotency key for the batch -- must be unique on your side). Free: no credit cost. Requires `confirmation_token` from `import_reviews_preview`.

[PREVIEW] Bulk-upload reviews from a custom source (Advanced API / Custom). Required: `reviews` (array of review objects per AppFollow's bulk upload schema), `ext_id` (a client-supplied idempotency key for the batch -- must be unique on your side). Free: no credit cost. Returns a `confirmation_token` to pass to `import_reviews`. The preview itself is free and changes nothing.

List the apps tracked in one collection. Required: `apps_id` (the collection's `collectionId` from `list_collections`). Optional: `extended` (true adds `rating`, `ratingCount` and `version` per app). Returns `{apps: [{appId, itemId, extId, store, isCompetitor, isFavorite, isArchived, title, dev, device, icon, ...}]}`. `extId` is the app's store id, the `ext_id` other tools take; `itemId` is the app's id inside this collection. `store` is the LONG store name, while every `store` argument takes the short code: `itunes` = `as`, `googleplay` = `gp`, `microsoftstore` = `ms`, `amazon` = `am`, `macstore` = `mc`, `xstore` = `xs`, `samsung` = `sg`, `trustpilot` = `tp`, `huaweiappgallery` = `hg`, `steam` = `st`. No pagination: one call returns every app of the collection that is not archived. Free: no credit cost.

List the user's collections (AppFollow workspaces that group tracked apps). Returns `{collections: {<collectionCode>: {collectionId, collectionCode, collectionName, countApps, countCompetitors, countries, languages, defaultCountry, defaultLang, created}}, sortedCollections: [<collectionCode>, ...]}`. `collectionId` is the `apps_id` other tools take; `collectionCode` is the lowercase slug other tools take as `collection_name`; `collectionName` is the display title and is never an argument. `sortedCollections` lists the codes in creation order. Call this first to learn what the user tracks. No arguments. No pagination: one call returns every collection. Free: no credit cost.

List the keywords AppFollow is tracking for an app, with per-keyword ASO scores. Required: `ext_id`. Optional: `country`, `device` (e.g. `iphone`), `date` (defaults to yesterday, UTC), `page`. Costs 12 credits. Read-only. **Each row of `keywords.list`** carries `kw` (the keyword text), `pos` (current rank position), `popularity` (search-traffic score, 0-100) and `score` (secondary AF score, often null), plus `effectiveness` (Keyword Effectiveness Index, 0-100; >20 means worth putting in the app title/subtitle) only when the account has the Keyword Effectiveness feature and `difficulty` (Top-10 ranking difficulty, 0-100) only when it has Keyword Difficulty. A tracked keyword with no position is not in `list`: it is listed in `keywords.no_pos` as a plain keyword string, not an object. See https://support.appfollow.io/hc/en-us/articles/360020831817-Keyword-Tracking for what each score means. Changing the tracked set is a separate write operation -- see `edit_keywords`, which REPLACES the whole set.

[WRITE] Remove one app from a collection so AppFollow stops tracking it there: the inverse of `add_app`, and the way to free the app or competitor slot an `add_app` took. Required: `store` (the short store code; `list_apps` shows the long name: `itunes` = `as`, `googleplay` = `gp`, `microsoftstore` = `ms`, `amazon` = `am`, `macstore` = `mc`, `xstore` = `xs`, `samsung` = `sg`, `trustpilot` = `tp`, `huaweiappgallery` = `hg`, `steam` = `st`), `ext_id` (the app's store id), `apps_id` (the collection's `collectionId` from `list_collections`). Call `list_apps` with the same `apps_id` first and show the user the app that will be removed (`title`, `store`, `isCompetitor`) before confirming; an archived app is not listed there but is still found and removed, so for an archived app show the user the `ext_id` and `store` you are about to remove. The confirmed call looks the app up in the collection by `ext_id` and `store`, archived apps included (free), and removes that one item; an app not in the collection fails with NOT_FOUND and is not charged. Returns `{ok: true}`. Costs 200 credits per confirmed call. Requires `confirmation_token` from `remove_app_preview`.

[PREVIEW] Remove one app from a collection so AppFollow stops tracking it there: the inverse of `add_app`, and the way to free the app or competitor slot an `add_app` took. Required: `store` (the short store code; `list_apps` shows the long name: `itunes` = `as`, `googleplay` = `gp`, `microsoftstore` = `ms`, `amazon` = `am`, `macstore` = `mc`, `xstore` = `xs`, `samsung` = `sg`, `trustpilot` = `tp`, `huaweiappgallery` = `hg`, `steam` = `st`), `ext_id` (the app's store id), `apps_id` (the collection's `collectionId` from `list_collections`). Call `list_apps` with the same `apps_id` first and show the user the app that will be removed (`title`, `store`, `isCompetitor`) before confirming; an archived app is not listed there but is still found and removed, so for an archived app show the user the `ext_id` and `store` you are about to remove. The confirmed call looks the app up in the collection by `ext_id` and `store`, archived apps included (free), and removes that one item; an app not in the collection fails with NOT_FOUND and is not charged. Returns `{ok: true}`. Costs 200 credits per confirmed call. Returns a `confirmation_token` to pass to `remove_app`. The preview itself is free and changes nothing.

[WRITE] Post a reply to a specific review. Required: `apps_id` (the workspace's `collectionId` from `list_collections`), `store` (the short store code, the review's `metaInformation.store`), `ext_id` (the app's store id), `review_id` (the store's review id: `reviewId` from `get_reviews`, NOT AppFollow's internal `id`), `answer_text`. Costs 3 credits per confirmed call. A rejected reply (duplicate, too long, limit reached, review not found) is refunded. Requires `confirmation_token` from `reply_to_review_preview`.

[PREVIEW] Post a reply to a specific review. Required: `apps_id` (the workspace's `collectionId` from `list_collections`), `store` (the short store code, the review's `metaInformation.store`), `ext_id` (the app's store id), `review_id` (the store's review id: `reviewId` from `get_reviews`, NOT AppFollow's internal `id`), `answer_text`. Costs 3 credits per confirmed call. A rejected reply (duplicate, too long, limit reached, review not found) is refunded. Returns a `confirmation_token` to pass to `reply_to_review`. The preview itself is free and changes nothing.

[WRITE] Flag a review with the store as a concern (spam, abusive, etc.). Required: `store` in long form (`googleplay`/`appstore`), `ext_id`, `review_id`, `concern_type` (e.g. `Spam`, `Abusive`), `concern_explanation`. Requires `confirmation_token` from `report_review_concern_preview`.

[PREVIEW] Flag a review with the store as a concern (off topic, spam, offensive content or other). Required: `store` in long form (`itunes` for the App Store, or `googleplay`; `appstore` is rejected), `ext_id`, `review_id`, `concern_type` (exactly one of `Off_Topic`, `Spam`, `Offensive_Content` or `Other`; case-sensitive), `concern_explanation`. Costs 3 credits per confirmed call. No confirmed call can succeed today: the legacy API refuses the short store code the gateway forwards (a billed VALIDATION_ERROR). Returns a `confirmation_token` to pass to `report_review_concern`. The preview itself is free and changes nothing.

Semantic-filtered review list: each returned review carries `tags` and a `sentiment` label (Positive/Negative/Neutral/Mixed). This is a FILTER over reviews, not a free-text search. **Costs 48 credits**. No paging: narrow with `sentiment`, `tag`, `rating`, or a date window rather than fetching pages. Needs the Semantic Analysis feature on the account; without it the call answers ACCESS_DENIED. Read the payload defensively (do not assume a specific field shape). Required: `ext_id`.

Send the user's own feedback to the AppFollow team. Call this ONLY when the user explicitly asks to send feedback to AppFollow, or asks for something AppFollow cannot do and wants that request passed on. Never call it on your own initiative. `message` is the user's feedback in their own words, nothing else from the conversation. It is sent from the user's AppFollow account. Free, no credits. Returns `{status: RECORDED}`, or `{status: LIMIT_REACHED}` after 5 messages in 24 hours.

Returns the currently-authenticated AppFollow user, the company (client) they belong to, and a pre-rendered `greeting_template` you should use to introduce yourself as **AppFollow Copilot** at the start of the conversation: email, name, company, user_id, client_id, is_appfollow_staff, greeting_template. Free (no credit cost, no upstream call -- pulled directly from the OAuth session). Read-only, no arguments.