AppTail – ASO & Keyword Research

Get Landscape

get_landscape

Read-only

Who the App Store shows beside one of your apps for the terms it competes on, in one storefront: every app in the niche with how many of your terms it ranks for and owns the top 10 for, its ratings, its review flow and its size, plus which apps arrived or fell out this window — and term_gap, how much of the niche's own vocabulary you do not track yet, with the biggest holes ready for add_keywords. This is the niche, not your watchlist: most rows are apps nobody added, and get_competitors answers the other question.

Input Schema

TableJSON Schema

Name	Required	Description
`to`	No	End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.
`from`	No	Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.
`app_id`	Yes	Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id).
`period`	No	The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling.
`country`	No	Storefront to read the niche in (e.g. US, GB). A niche exists per storefront and is never blended across them. Defaults to the first of the account's focus_countries this app is actually tracked in, then the app's primary storefront.

Output Schema

TableJSON Schema

Name	Required	Description
`count`	Yes	Members returned.
`terms`	Yes	How many terms defined this niche: the account's tracked terms for this app in this storefront, plus the terms the app already holds a top-10 position for. Every `terms` and `top10_terms` figure below is out of this.
`total`	Yes	Members the niche actually holds. Larger than `count` means the list was cut.
`app_id`	Yes	The app whose niche this is.
`window`	Yes	The window used, and what the change figures are measured against.
`caveats`	Yes	Sentences the reader has to hear before the numbers mean what they look like they mean — a cut list, hidden rows, an unmeasurable gap, modelled sizes. Pass these on; do not summarise them away.
`country`	Yes	The storefront actually read, which may not be the one asked for.
`members`	Yes	The niche, most of the account's terms owned first. `entered` and `left` mark this window's movers.
`app_name`	No	Its name.
`term_gap`	Yes	How much of the niche's vocabulary the account is not watching.
`truncated`	Yes	True when `count` is less than `total`. Say the list is partial rather than presenting it as the whole niche.
`visibility`	No	The basis of each member's `visibility`. Null when it could not be read just now — then every member's `visibility` is null too, which is unknown, not zero.
`console_url`	No	This landscape in the console, in this storefront.
`hidden_count`	Yes	Apps the account owner has hidden from this landscape in the console. They are excluded from `members`, from the movers and from `term_gap` alike.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 4, 2026

addedOutput schema / properties / members / items / properties / visibility

Added value: +{
+  "description": "Search Visibility, 0–100, on the account's **tracked non-brand terms** in this storefront: the same score get_keywords gives your app, computed for this one — 100 = #1 on every term, the mean of the last 7 days. **Not `share` rescaled, and not in its order**: `share` is over this landscape's wider corpus (it adds the terms the app ranks top 10 for untracked, and brand terms) at each app's best place in the window. 0 is a measurement — nothing in the top 50 on those terms. Null when the account's terms here cannot be scored or the read failed — top-level `visibility.reason` / `caveats` say which.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / visibility

Added value: +{
+  "description": "The basis of each member's `visibility`. Null when it could not be read just now — then every member's `visibility` is null too, which is unknown, not zero.",
+  "properties": {
+    "rank": {
+      "description": "Your place among the apps scoring above zero on those terms. Null with no score, or at zero.",
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "ranked": {
+      "description": "How many apps score above zero on those terms — the whole top 50, not only the listed members.",
+      "type": "integer"
+    },
+    "reason": {
+      "description": "Why there is no score, with the fix.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "score": {
+      "description": "Your app's Search Visibility here — the same number as get_keywords `visibility.score` for this storefront.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "terms_scored": {
+      "description": "The tracked non-brand terms every member's `visibility` is over.",
+      "type": "integer"
+    }
+  },
+  "type": [
+    "object",
+    "null"
+  ]
+}

First observedOct 2, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context on top: the niche is storefront-scoped and not blended, rows include apps 'nobody added', and the window determines which apps 'arrived or fell out'. It omits any row limit or rate-limit note, which is the only gap.

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?

Two sentences, front-loaded with the core purpose before the term_gap detail and the sibling routing. It is dense and em-dash-heavy, making it slightly hard to scan, but every clause carries distinct information and nothing is padding.

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?

An output schema exists, so return values need not be re-explained, and the description covers scope, sibling routing and follow-up actions. The only thing an agent might still wonder — how many rows come back or whether results are capped — is left unstated, keeping this just short of full completeness.

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 every parameter (to, from, app_id, period, country) is already documented in the schema with formats, defaults and override rules. The description only implicitly touches country ('one storefront') and period ('this window'), adding no syntax or meaning beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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?

The description names a specific resource (the niche landscape around one app in one storefront) and enumerates exactly what comes back: per-app ranking counts, top-10 ownership, ratings, review flow, size, arrivals/departures, plus term_gap. It explicitly separates itself from get_competitors by stating 'This is the niche, not your watchlist,' so an agent can distinguish 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 Guidelines5/5

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

It names the alternative (get_competitors) and the condition that selects it ('answers the other question'), and routes the follow-up work to add_keywords for the biggest term_gap holes. It also states the scope constraint that governs use — one storefront, never blended — which tells the agent this is a per-market read.

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

All AppTail – ASO & Keyword Research tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?