MCP Apple Ads

Apple Ads: Get Search Term Popularity

apple_ads_get_search_term_popularity

Read-only

Retrieves ranked App Store search terms by country and genre to reveal actual keyword demand and support keyword research.

Instructions

The most-searched terms on the App Store, ranked, per country and genre — Apple's own demand data (terms with 500+ searches). The discovery side of keyword research: run it for your app's genre and market to see what people actually type, then pair with apple_ads_suggest_keywords. MONTHLY refreshes on the 5th; WEEKLY_SUN_SAT on Mondays.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "startDate": "<startDate>",
      "endDate": "<endDate>"
    },
    "name": "apple_ads_get_search_term_popularity"
  }
}

Input Schema

Name	Required	Description	Default
`genre`	No	App Store genre to rank within. Apple's list is coarser than the store's categories: no Navigation (use TRAVEL or SPORTS), no Developer Tools (use PRODUCTIVITY_UTILITIES).
`limit`	No	How many records to return (1-1000). Apple's own maximum page size is 5000.
`terms`	No	Restrict to these search terms, to check demand for a candidate list.
`offset`	No	Rows to skip, for paging. The response's `pagination` block says how many exist.
`endDate`	Yes	Last day of the range, YYYY-MM-DD. For MONTHLY, the last day of a month.
`savePath`	No	Absolute path to also write this result to, as pretty-printed JSON. Use it rather than copying values out of the response into a file by hand. Parent directories are created.
`countries`	No	ISO 3166-1 alpha-2 country codes, e.g. ["FR"]. Strongly recommended.
`startDate`	Yes	First day of the range, YYYY-MM-DD. For MONTHLY, the 1st of a month.
`adAccountId`	No	The ad account to act on. Omit it when you have exactly one or APPLE_ADS_AD_ACCOUNT_ID is set — it is resolved automatically. List them with apple_ads_list_accounts.
`granularity`	No	MONTHLY is a calendar-month snapshot; WEEKLY_SUN_SAT a Sunday-Saturday week.	MONTHLY

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 7, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true is consistent with a pure read of Apple's demand data. Beyond the annotations, the description discloses genuinely useful behavioral traits: the data source and its 500+ search cutoff, plus refresh cadence ('MONTHLY refreshes on the 5th; WEEKLY_SUN_SAT on Mondays') that tells an agent how stale results may be. It does not mention rate limits or result ordering details, so a 4 rather than 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what the data is and followed by how to use it and its refresh schedule. Dense but every clause carries information; the terse 'MONTHLY refreshes on the 5th; WEEKLY_SUN_SAT on Mondays' is compact rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only analytics tool with 10 parameters, full schema coverage, and no output schema, the description covers purpose, sourcing, freshness, and the companion tool. It even points at the response's `pagination` block, so paging behavior is discoverable; only the shape of returned rows is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains genre coarseness, limit/offset paging, the terms filter, savePath, and the date format — the description adds no parameter-level detail beyond the country/genre framing. Baseline 3 is appropriate when structured fields carry the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb-and-resource: the most-searched App Store terms, ranked, per country and genre, sourced from Apple's own demand data with a 500+ search threshold. It also positions itself against the sibling apple_ads_suggest_keywords as 'the discovery side of keyword research,' so an agent can separate the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit usage pattern — 'run it for your app's genre and market to see what people actually type, then pair with apple_ads_suggest_keywords' — which covers when to reach for this tool and what to combine it with. It stops short of stating when NOT to use it (e.g., for campaign-level performance, use apple_ads_get_report instead), which keeps it from a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.