LocalASOMCP and AI agents
LocalASO keywords_check tool: rank, volume and difficulty checks with a 60-check cap
keywords_check fetches rank, volume and difficulty for keywords already on a board, waits until the checks finish and returns the results. It runs at most 60 checks per call; the remaining field says how many are left, and the agent calls the tool again for those.
Updated
Arguments
| Argument | Type | Required | Meaning |
|---|---|---|---|
app | string | yes | Internal id, App Store trackId, or part of the app name |
terms | string[] | no | Only check these board keywords. Matching is case-insensitive. When omitted, all board keywords are considered |
countries | string[] | no | Only check these storefronts, using codes such as US, DE, JP. When omitted, all of the board's countries are considered |
terms selects keywords that are already on the board. A term that is not on the board is simply not matched; use board_add_keywords to add it first.
The 60-check cap
One check is one keyword phrase in one country. The tool builds the list of checks due, runs the first 60 and reports the rest in remaining. The arithmetic is simple:
| Keywords | Countries | Checks | Calls needed |
|---|---|---|---|
| 20 | 3 | 60 | 1 |
| 20 | 4 | 80 | 2 (60, then remaining: 20) |
| 50 | 5 | 250 | 5 |
Because the tool waits for the queue to finish before it returns, a call with 60 checks takes as long as the rate limiter allows.
Rate-limit behavior
The MCP server runs its own rate limiter, 15 requests per minute by default, and shares the 6-hour response cache with the app. The limiter is separate from the one inside the running app, so a large check in the desktop app and a large check through an agent at the same time compete for the same public Apple search endpoint. Run one at a time. The only outside traffic is the public Apple search requests that rank checks make.
Output
| Field | Meaning |
|---|---|
app | Summary: id, trackId, name, isOwn, mainCountry |
checked | Number of checks run in this call |
remaining | Checks due but not run because of the cap |
queue | The check queue's status after the call |
results | One entry per checked keyword and country: term, country, phrase, rank, volume, difficulty, verdict |
rank is a number, "200+" when the app was not found, or null if the cell has no check. Volume and difficulty are 0 to 100 estimates from rating counts, not Apple search counts. The verdict is Swap, Dead, Hard, Push or Maybe.
A loop an agent should follow
This is an example instruction, not recorded output: "Call keywords_check for my app. If remaining is greater than zero, call it again with the same arguments until remaining is zero, then summarize the results by verdict." A good agent stops when remaining reaches 0 and does not retry on a checked of 0.
Failure modes
- No valid license: the tool returns the licensing message and checks nothing.
- Unknown country code or ambiguous app name: the tool returns an error text, with the candidates for an ambiguous name.
- Very slow calls: the limiter, not the tool, sets the pace. Narrow
termsorcountriesfor faster feedback.
Next step
Read the checked board with board_get. To interpret the numbers, see keyword difficulty and the search volume guide. The full tool reference is in the MCP docs.
Questions
- What does remaining mean?
- It is the number of checks that were due but not run in this call because of the 60-check cap. Call the tool again to run them.
- Can keywords_check add new keywords?
- No. It matches terms against keywords already on the board. Add new ones with board_add_keywords first.
Do this for every country, in minutes