Asonix MCP
MCP tools
The Asonix MCP server at https://api.asonix.io/mcp gives your agent these 33 tools. You do not call them yourself: ask in plain words, and your agent picks the tools it needs. This page lists what each tool does and the inputs it takes.
get_ai_visibility_overview
Read-onlyAI Visibility Overview
Read a tracked app's stored AI recommendation benchmark: coverage, mention/recommendation/App Store citation rates, weekly history and topic/prompt summaries with run IDs. Not ASO visibility. No collection or model calls. Defaults to four weeks; no benchmark returns NOT_STARTED. Use list_apps to resolve the app and storefront.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | 1–128 characters |
| country | string | Optional | Exact storefront, e.g. us. Defaults to us; use the tracked app's home country |
| platform | string | Optional | One of: ios, ipad, mac |
| weeks | integer | Optional | 1–12. Default: 4 |
get_ai_visibility_reasons
Read-onlyAI Recommendation Reasons
Read cached recommendation themes, exact answer quotes and description passage matches. Includes analysis status, timestamps and its own evidence denominator (which can differ from the overview). No generation or refresh. Full descriptions stay in get_app_overview; this returns matched passages and description metadata. Use theme and evidenceLimit to drill into supporting quotes.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | 1–128 characters |
| country | string | Optional | Exact storefront, e.g. us. Defaults to us; use the tracked app's home country |
| platform | string | Optional | One of: ios, ipad, mac |
| theme | string | Optional | 1–200 characters |
| evidenceLimit | integer | Optional | 1–10. Default: 3 |
get_ai_visibility_evidence
Read-onlyAI Visibility Evidence
Read a saved AI Visibility answer by runId, or recent answers for one promptId (exactly one required). Defaults to one run; use nextBefore for older prompt runs. Citations, resolved mentions and classification coverage are included. includeTrace adds captured searches; their sources belong to a search call, not an individual query. No external requests or collection.
Give exactly one of: runId, promptId.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | 1–128 characters |
| country | string | Optional | Exact storefront, e.g. us. Defaults to us; use the tracked app's home country |
| platform | string | Optional | One of: ios, ipad, mac |
| runId | string | Optional | 1–128 characters |
| promptId | string | Optional | 1–128 characters |
| before | string | Optional | Exclusive scheduledFor cursor from nextBefore; only with promptId. Format: date-time |
| limit | integer | Optional | 1–5. Default: 1 |
| includeTrace | boolean | Optional | Default: false |
add_app
Makes changesAdd App
Add an App Store app to the current Asonix workspace by App Store ID or app name/search query.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Optional | |
| country | string | Optional | |
| name | string | Optional | |
| platform | string | Optional | One of: ios, ipad, mac |
| q | string | Optional |
create_unreleased_app
Makes changesCreate Unreleased App
Create a private unreleased app idea in the current Asonix workspace. Use this when the user's app is not on the App Store yet; then add researched keywords with add_keywords.
| Input | Type | Required | Details |
|---|---|---|---|
| country | string | Optional | |
| name | string | Optional | |
| platform | string | Optional | One of: ios, ipad, mac |
search_apps
Read-onlySearch Apps
Find App Store apps by name or developer, to get an app's appStoreId; use it before add_app when the user gives an app name. Returns at most 12 apps, in Apple's name-search order, which is not the keyword ranking: for who ranks for a keyword, use get_keyword_top_apps. Screenshot URLs only with includeScreenshots.
| Input | Type | Required | Details |
|---|---|---|---|
| country | string | Optional | |
| includeScreenshots | boolean | Optional | Include each app's screenshot URLs. Omitted by default: they were two thirds of an answer |
| limit | integer | Optional | 1–12 |
| platform | string | Optional | One of: ios, ipad, mac |
| q | string | Required |
add_keywords
Makes changesAdd Keywords
Add one or more tracked keywords to an app in the current Asonix workspace and queue ranking refresh so popularity, difficulty, opportunity, and rank evidence can be collected. For agent-researched candidates, call evaluate_keywords first and add app-relevant primary or secondary terms.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| keywords | array of string | Required | At least 1 item |
| platform | string | Optional | One of: ios, ipad, mac |
star_keyword
Makes changesStar Keyword
Star/favorite a keyword research keyword in the current workspace by keywordId or term.
| Input | Type | Required | Details |
|---|---|---|---|
| country | string | Optional | |
| keywordId | string | Optional | |
| term | string | Optional |
unstar_keyword
Makes changesUnstar Keyword
Remove a keyword research keyword from the current workspace favorites by keywordId or term.
| Input | Type | Required | Details |
|---|---|---|---|
| country | string | Optional | |
| keywordId | string | Optional | |
| term | string | Optional |
list_apps
Read-onlyList Apps
List apps tracked in the current Asonix workspace: names, App Store IDs, platforms, tracked storefronts, ratings and tracked-keyword counts. Pages with limit (default 20, max 100) and offset; q filters by name, developer, genre or ID. For one app's details use get_app_overview; for its keywords, list_tracked_keywords.
| Input | Type | Required | Details |
|---|---|---|---|
| limit | integer | Optional | 1–100 |
| offset | integer | Optional | At least 0 |
| platform | string | Optional | One of: ios, ipad, mac |
| q | string | Optional |
list_tracked_keywords
Read-onlyTracked Keywords
One tracked app's tracked keywords with rank, popularity, difficulty, relevance and an ad summary, in one storefront or all. Use it for "how are my keywords doing". For the app's listing or ratings, or an untracked app, use get_app_overview. Paged: limit (default 30, max 100) and offset. relatedTools gives the next page, refresh_app_rankings when ranks are over 18 hours old, and the overview.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| limit | integer | Optional | 1–100 |
| offset | integer | Optional | At least 0 |
| platform | string | Optional | One of: ios, ipad, mac |
get_app_meta_ads
Read-onlyApp Meta Ads
An App Store app's Meta ads (Facebook, Instagram, Messenger, Audience Network) from Asonix's monthly Ad Library crawl, worldwide, for any app: active ads with text, call to action, start date, platforms and an Ad Library link, and past ads with their dates. status not_found is not proof it never ran Meta ads: the crawl covers the App Store ads it found.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required |
refresh_app_rankings
Makes changesRefresh App Rankings
Queue a ranking refresh for one tracked app's keywords not checked in the last 18 hours, and return at once with jobIds. Omit country for every tracked storefront; one refreshed recently is listed in coolingDown. A refresh can take 10 minutes or more, so do not wait in a loop: tell the user ranks are updating, then call get_ranking_refresh_status after pollAfterSeconds, or read list_tracked_keywords later.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| platform | string | Optional | One of: ios, ipad, mac |
get_ranking_refresh_status
Read-onlyRanking Refresh Status
Report progress of a ranking refresh started by refresh_app_rankings, or of the rankingRefreshJob id returned by add_keywords: keywords done, failed, and remaining per storefront. Poll no more often than pollAfterSeconds. When finished is true, read the full updated ranks with list_tracked_keywords.
| Input | Type | Required | Details |
|---|---|---|---|
| jobIds | array of string | Required | 1–20 items |
get_workspace_keyword_opportunities
Read-onlyWorkspace Keyword Opportunities
Return top scored keyword opportunities across all tracked apps in the current Asonix workspace, including shipped and unreleased apps, all countries, and rank/popularity/difficulty/opportunity evidence. Use this for requests like analyzing all apps or finding the top 100 opportunities without reading a local database. Each opportunity has checkedAt; call refresh_app_rankings for an app whose ranks are old.
| Input | Type | Required | Details |
|---|---|---|---|
| country | string | Optional | |
| limit | integer | Optional | 1–200 |
| platform | string | Optional | One of: ios, ipad, mac |
check_tracked_keywords
Read-onlyCheck Tracked Keywords
Check candidate keyword terms against one tracked app's existing tracked keywords without dumping the full keyword table. iOS keyword rows include cached topAdvertisers; pending observations queue in the background. Use this before calling a candidate a missing gap, before add_keywords, and instead of inspecting local database code.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| keywords | array of string | Required | At least 1 item |
| platform | string | Optional | One of: ios, ipad, mac |
get_app_overview
Read-onlyApp Overview
An app's overview in one storefront, for any App Store app. storeListing is the storefront's listing and rating. Lists are counts: include adds the full description, countryRatings, listingCountries or keywordSuggestions. tracked says whether the workspace tracks it; its keywords: list_tracked_keywords. runsAppleSearchAds: yes if a sampled search ad showed the app in any country Asonix samples (7 days); unknown is not proof it does not advertise.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| include | array of string | Optional | Full lists to add: description, countryRatings, listingCountries, keywordSuggestions. Each item: One of: description, countryRatings, listingCountries, keywordSuggestions |
| platform | string | Optional | One of: ios, ipad, mac |
get_app_visibility_history
Read-onlyApp Visibility History
Return tracked ASO visibility score history for an app, useful for momentum and trend analysis.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| days | integer | Optional | 2–30 |
| platform | string | Optional | One of: ios, ipad, mac |
get_app_rank_history
Read-onlyApp Rank History
Return rank, popularity, or difficulty history for one tracked app keyword in a storefront.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| keyword | string | Required | |
| metric | string | Optional | One of: rank, popularity, difficulty |
| platform | string | Optional | One of: ios, ipad, mac |
get_app_rating_history
Read-onlyApp Rating History
Return stored public rating history for any App Store app, tracked or not, with deltas: the history the Inspect dialog shows. Asonix records rating history only while some workspace tracks the app, so an app no workspace has tracked has none; for current ratings of any app, use get_app_overview. Omit country or pass "all" to return every observed storefront plus the all-countries aggregate; pass a country code to return only that storefront.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | Optional App Store country to return. Omit it or pass "all" to return every stored country and the all-countries aggregate |
| platform | string | Optional | One of: ios, ipad, mac |
get_app_charts
Read-onlyApp Top Charts
Where any App Store app placed in Apple's iPhone top charts (free, paid, grossing; overall and by category) per storefront: best rank, days on chart, latest position. days: 7, 30 (default), 90 or 365. includeDailyCells adds a cell per chart per day: a number is the best position, -N absent from the top N, e empty chart, x not captured, u not collected yet, p pending; 90 and 365 days cover one storefront. iPad and Mac apps: iphone_only.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | matches ^[1-9][0-9]{0,18}$ |
| country | string | Optional | |
| days | integer | Optional | One of: 7, 30, 90, 365 |
| includeDailyCells | boolean | Optional | |
| platform | string | Optional | One of: ios, ipad, mac |
get_keyword_suggestions_for_app
Makes changesApp Keyword Suggestions
Refresh and return Asonix keyword suggestions for one tracked app and storefront. Includes suggestionRelevance rows and inline metadata-plan relevanceScore/relevanceStatus; missing scores queue in the background.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| platform | string | Optional | One of: ios, ipad, mac |
research_app_keywords
Makes changesResearch App Keywords
Start keyword research for a tracked app in one call: Asonix suggestions, known public rankings and market keyword opportunities, each with the app's relevance. It can refresh the suggestion list, which spends the app's daily budget. Seed searches are checked privately unless storePublicly is true. Pending ad observations and relevance scores fill in on a later call. Classify candidates with evaluate_keywords before recommending or adding them.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| excludeBrands | boolean | Optional | |
| competitorLimit | integer | Optional | 1–10 |
| includeCompetitors | boolean | Optional | |
| limit | integer | Optional | 1–25 |
| platform | string | Optional | One of: ios, ipad, mac |
| q | string | Optional | |
| refreshSuggestions | boolean | Optional | |
| seed | string | Optional | |
| sort | string | Optional | One of: revenue, downloads, opportunity, popularity, difficulty |
| storePublicly | boolean | Optional |
extract_competitor_keywords
Makes changesCompetitor Keywords
Extract keyword opportunities from competitor public rankings and compare them against the tracked app. Includes relevanceScore/relevanceStatus for the target app, not the competitors; missing scores queue in the background. Provide competitorAppStoreIds, or provide a seed keyword to discover competitors from a private live SERP unless storePublicly is true. Rank and classify candidates with evaluate_keywords before recommending or adding them.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| competitorAppStoreIds | array of string | Optional | |
| competitorIds | array of string | Optional | |
| competitorLimit | integer | Optional | 1–10 |
| competitors | array of string | Optional | |
| country | string | Optional | |
| keyword | string | Optional | |
| limit | integer | Optional | 1–25 |
| platform | string | Optional | One of: ios, ipad, mac |
| q | string | Optional | |
| seed | string | Optional | |
| storePublicly | boolean | Optional |
get_localization_opportunities
Makes changesLocalization Opportunities
Build and return localization and translated market keyword opportunity requests for one tracked app.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| platform | string | Optional | One of: ios, ipad, mac |
get_public_app_rankings
Read-onlyPublic App Rankings
Return known public App Store keyword rankings where an app appears in collected SERPs.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | |
| country | string | Optional | |
| limit | integer | Optional | 1–20 |
| offset | integer | Optional | At least 0 |
| platform | string | Optional | One of: ios, ipad, mac |
search_keywords
Read-onlySearch Keywords
Search Asonix keyword research summaries by query, market, platform, scores, and market estimates. iOS keyword rows include cached topAdvertisers; pending observations queue in the background, so retry this tool later.
| Input | Type | Required | Details |
|---|---|---|---|
| country | string | Optional | |
| excludeBrands | boolean | Optional | |
| limit | integer | Optional | 1–100 |
| maxDifficulty | integer | Optional | 0–100 |
| maxDownloads | integer | Optional | At least 0 |
| maxKeywordLength | integer | Optional | At least 1 |
| maxOpportunity | integer | Optional | 0–100 |
| maxPopularity | integer | Optional | 0–100 |
| maxRevenue | integer | Optional | At least 0 |
| minDifficulty | integer | Optional | 0–100 |
| minDownloads | integer | Optional | At least 0 |
| minOpportunity | integer | Optional | 0–100 |
| minPopularity | integer | Optional | 0–100 |
| minRevenue | integer | Optional | At least 0 |
| page | integer | Optional | At least 1 |
| platform | string | Optional | One of: ios, ipad, mac |
| q | string | Optional | |
| sort | string | Optional | One of: revenue, downloads, opportunity, popularity, difficulty |
| starred | boolean | Optional |
get_keyword_relevance
Read-onlyKeyword Relevance
App-specific relevance (0–100) of up to 100 keywords for a tracked app, from the same scorer as the UI. Returns at once with ready, pending, failed or unavailable for each keyword. Pending is not zero: call again after 3 seconds or more, backing off. retry=true retries failed work after its cooldown. Adds nothing to tracking or public research. country defaults to us and platform to ios.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | At least 1 character |
| country | string | Optional | |
| platform | string | Optional | One of: ios, ipad, mac |
| keywords | array of string | Required | 1–100 items. Each item: 1–200 characters, not blank |
| retry | boolean | Optional |
evaluate_keywords
Makes changesEvaluate Keywords
Rank and classify candidate keywords by Asonix popularity, difficulty and opportunity. Use it before recommending keywords or calling add_keywords. Known keywords reuse stored scores; up to 20 new ones per call are scored privately, without adding them to public research. Pass popularityScore and difficultyScore to judge your own values. appStoreId adds app relevance; pending is not zero (get_keyword_relevance).
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Optional | Optional tracked target app for inline relevance scores. At least 1 character |
| country | string | Optional | |
| excludeBrands | boolean | Optional | |
| keywords | array of string or object | Required | 1–50 items. Object fields: difficultyScore (0–100), keyword, opportunityScore (0–100), popularityScore (0–100), term |
| maxDifficulty | integer | Optional | 0–100 |
| minOpportunity | integer | Optional | 0–100 |
| minPopularity | integer | Optional | 0–100 |
| platform | string | Optional | One of: ios, ipad, mac |
get_keyword_top_apps
Read-onlyKeyword Top Apps
Who ranks for a keyword in one storefront; appStoreId gives that app's rank. Uses results Asonix checked in the last 18 hours, else a private live check; saves nothing. Adds stored scores when Asonix has them; to score a new keyword, use evaluate_keywords. To find an app by name, use search_apps. runsAppleSearchAds: yes if a sampled search ad showed the app in any country Asonix samples (7 days); unknown is not proof it does not advertise.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Optional | An app to find in the results: targetApp gives its rank, also beyond limit |
| country | string | Optional | |
| includeScreenshots | boolean | Optional | Include screenshot URLs for the first 10 apps |
| keyword | string | Optional | The keyword text. Give this or keywordId |
| keywordId | string | Optional | An Asonix keyword ID, from search_keywords for example |
| limit | integer | Optional | 1–100 |
| platform | string | Optional | One of: ios, ipad, mac |
get_keyword_top_advertisers
Read-onlyKeyword Top Advertisers
Apps seen in native App Store search ads for one iPhone keyword in one Apple Ads country: the last 7 days' check coverage, last seen, and 30 days of history. Cached only, no live Apple request; pending collection fills in on a later call. Absence does not prove an app stopped bidding or was outbid. Needs country and exactly one of keywordId or term.
| Input | Type | Required | Details |
|---|---|---|---|
| country | string | Required | One of 91 values: ae, al, am, ar, at, … |
| keywordId | string | Optional | 1–100 characters |
| term | string | Optional | 1–200 characters |
| platform | string | Optional | One of: ios |
get_app_search_ads_keywords
Read-onlyApp Paid Keywords
Keywords where an iPhone app's App Store search ads were seen in the last 30 days, in all countries or one. Asonix checks each keyword about once a day, so a missing keyword may still be bid on. observedSharePercent7d is the share of the last 7 days' checks that showed the ad, not impression share. organicRank is null when the app is not in the latest results. status unavailable means ad data is off, not no ads.
| Input | Type | Required | Details |
|---|---|---|---|
| appStoreId | string | Required | matches ^[0-9]{1,20}$ |
| country | string | Optional | One of 91 values: ae, al, am, ar, at, … |
get_keyword_history
Read-onlyKeyword History
Return keyword popularity or difficulty history for an Asonix keyword, with cached topAdvertisers for eligible iOS keywords. Pending advertiser observations are queued; retry later.
| Input | Type | Required | Details |
|---|---|---|---|
| country | string | Optional | |
| keywordId | string | Required | |
| metric | string | Optional | One of: popularity, difficulty |
| platform | string | Optional | One of: ios, ipad, mac |