Did a change work?

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

Beyond the readOnly/idempotent annotations, the description discloses real behavioral constraints: the change day is excluded from windows, other changes overlapping the window contaminate results, App Store Connect data lags 1-2 days while Google Play posts monthly, and unreleased App Store text yields waiting_for_release with day/liveDay/sentDay semantics. It also states plainly that this shows correlation around a change, not causal proof.

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?

The content is all substantive, but it is delivered as a single dense block riddled with nested parentheses and run-on clauses (the verdict, coverage, and overlap caveats all collide mid-sentence). Front-loading the change types is good, yet the metric and verdict definitions would be far easier to parse as a short list; an agent extracting the calling rules has to work hard.

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?

With no output schema, the description carries the return-value burden and does so well: it defines each metric, the verdict enum, and the line-per-change vs full-expansion output format. Only minor gaps remain, such as behavior when no changes exist at all.

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 coverage is 100%, so baseline is 3, but the description adds meaningful semantics the schema does not: eventId defaults to the newest change, unselected changes come back one line each while the selected event is expanded per market, and supplying market switches to a single-market full view. That clarifies how the parameters change the shape of the response.

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 opens by enumerating exactly which changes are measured (ASOMaster-published listing text, re-read store text, a new app version with its release day, owner-added markers) and what is computed before vs after, so an agent can tell this is a change-impact report. It does not name or differentiate itself from any sibling (e.g., list_rival_changes, get_audit), so it stops short of a 5.

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?

Usage is implied through the verdict vocabulary (too_early, not_enough_data, waiting_for_release) and the caveat that overlapping changes mix effects in, which tells the agent when results are trustworthy. However, there is no explicit when-to-use/when-not-to-use statement and no routing to an alternative tool for a different question.

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