AppTail – ASO & Keyword Research

Explain Period

explain_period

Read-only

Return an account or owned-app summary for a requested period: available measured App Store Connect performance, storefront changes, tracked keyword movements, recorded signals, review volume and the last sent digest. Returns comparison data, coverage and caveats identifying unavailable sections. Reads account data without changing tracking or publishing content.

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`	No	Narrow to one of the account's own apps — get_account lists them. Omit for the whole portfolio, which excludes apps the owner has hidden.
`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 `last_month`. 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.
`compare`	No	What to read the period against. `previous` (the default) is the period immediately before — for a calendar month, the calendar month before. `year_ago` is the same dates a year earlier, for comparison with the corresponding period in the previous year.
`country`	No	Storefront for the keyword half only; the money is reported across all of them with a per-storefront split. Defaults to the app's primary storefront. Ranks only exist per storefront.

Output Schema

TableJSON Schema

Name	Required	Description
`digest`	No	What the customer was last mailed — the weekly digest, sent Wednesdays, that leads with the measured week and at most three moves. Null when none has gone out yet. Anything here is breakfast reading, not news: say "as your digest said" rather than presenting it as a discovery, and lead with what happened since `sent_at`.
`window`	Yes	The window actually read, which is not always the one asked for: an inverted range is swapped, a range past three years is shortened, and first-party figures are pulled back to the last day App Store Connect reported. Quote these dates, not the requested ones.
`app_ids`	Yes	The apps this covers.
`caveats`	Yes	Everything the reader has to hear before this reads as a complete picture: apps with no connection, a window shortened to the last day Apple reported, a corpus larger than the movers shown. Pass these on. A composed answer that drops them is the confident-and-wrong failure this tool exists to avoid.
`reviews`	Yes	Review arrivals — a flow, counted over the period. Not the backlog of unanswered reviews, which has no window and is on the console's reviews screen.
`signals`	Yes	What the product itself detected. A stored record, not a reconstruction — quote these sentences rather than re-deriving them from the numbers.
`headline`	Yes	The two or three sentences a person would open with, each carrying its own figures. Lead with these; everything below is the evidence for them.
`keywords`	No	The keyword half. Null when the account tracks no apps.
`performance`	No	The measured half. Null when the account has no apps at all, and present with null figures when it has apps but no App Store Connect connection — those are different answers, and the caveats say which.
`comparison_window`	No	What everything here is read against. Null when `compare` was `none`.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 2, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description still adds real behavioral context beyond that: output includes comparison data, coverage and caveats identifying unavailable sections, and it explicitly states reads do not change tracking or publishing content.

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?

Front-loaded with what is returned, then a second sentence on return shape and read-only behavior. The enumerated section list is long but each item earns its place by defining the aggregate; no filler or throat-clearing.

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?

With an output schema present, the description needn't detail return values, yet it usefully flags caveats and unavailable-section coverage. Safety is covered by annotations and all six parameters are fully documented in the schema, leaving only the missing when-to-use/routing guidance as a gap.

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 baseline is 3; the schema already explains default windows, from/to precedence, app_id scoping, and the compare enum. The description adds little parameter-level meaning beyond restating that it covers a requested period and noting per-storefront money reporting (which the schema attributes to country).

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?

Specific verb (Return) on a specific resource (account or owned-app summary) scoped to a requested period, with the aggregated sections enumerated: performance, storefront changes, keyword movements, signals, review volume, last digest. The aggregate role clearly separates it from single-purpose siblings like get_performance, get_signals, and get_reviews without needing to name them.

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

Usage Guidelines3/5

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

No explicit when-to-use statement, no exclusions, and no routing to alternatives such as get_performance or get_reviews when only one section is wanted. Usage is only implied by the aggregate framing plus the schema's detailed parameter guidance, which the agent must infer triggers this tool rather than a narrower sibling.

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?