play_store_stats

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

With no annotations provided, the description carries the safety burden and does disclose 'read-only' and the backing bucket (SEO_MCP_PLAY_BUCKET), both beyond what the schema states. The deeper quirks — missing files being normal and storePerformanceTotals not being a rollup — are documented in parameter descriptions rather than the tool description, so disclosure is strong but not maximal.

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

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

Three sentences with purpose front-loaded and config/safety placed last; every sentence earns its place for a 10-parameter tool. The middle sentence is a long run-on covering several parameters, which slightly hurts scannability but remains efficient overall.

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

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

For a 10-parameter tool with no annotations, the description covers purpose, key parameter interactions, the backing bucket, and safety in three sentences, while the 100%-coverage schema and output schema carry the remaining parameter and return-value documentation. It is missing explicit sibling differentiation and operational details such as rate limits or auth, which would push it to a 5.

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

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 description restates parameter behavior (installsDimension breakdown values, include report families, startDate/endDate window semantics) that the schema already documents in equal or greater detail, adding little new meaning beyond a compact framing.

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

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

The description names a specific verb and resource — 'Read Google Play bulk reports for an app' — and enumerates the exact data families (active device installs, store-listing visitors, acquisitions by traffic source). The explicit 'Google Play' framing sets it apart from the app_store_* Apple siblings and from play_vitals, so an agent can pick it without opening the schema.

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

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

The data domain is precise enough that for Play installs or store-listing metrics this is the obvious tool, but the description never states when not to use it or names alternatives such as play_vitals. Usage context is implied from the domain wording rather than explicitly guided.

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