App Pain API

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description's only added behavioral information is 'when available' for the star histogram, signaling partial/optional fields — useful but thin. Nothing about behavior for unknown ids, store mismatch, or country fallback.

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?

One front-loaded sentence with no filler; the caveat '(when available)' is placed inline rather than wasting a separate sentence. It is telegraphic rather than ungrammatical, and nothing could be trimmed without losing field information.

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 does the necessary work of naming the returned fields, which is appropriate for a read-only lookup. However, it omits failure behavior (app not found), whether the histogram is separate data or an aggregate, and any guidance on selecting between this and the other per-app tools — gaps for a tool with three siblings operating on the same app.

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%, and the schema already explains accepted appId forms, store inference, and the country default. The description adds no parameter guidance beyond the schema, so the baseline 3 applies.

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 enumerates the exact payload (name, developer, category, price, rating, rating count, star histogram) for a single app, which makes the resource and its boundaries clear against siblings like get_app_reviews or get_version_history. It never states the retrieval verb or that it is a single-app lookup, relying on the tool name for that, so it falls just 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?

There is no statement of when to call this versus get_app_reviews, get_pain_trend, get_version_history or search_apps, and no prerequisites are given. The only routing hint ('get ids from search_apps') lives in the appId schema description, not in the tool description.

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

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

Annotations already declare read-only, idempotent and open-world access, so the description is free to focus on payload characteristics. It discloses the page size and the fields returned (rating/title/body/version/date/devReply/thumbsUp), which matters because there is no output schema. It doesn't mention the 10-page ceiling or Android-only sorting, but those appear in the schema.

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?

Two tight sentences: what it returns and where it fits in a workflow. It is front-loaded with the verb and resource, and every clause carries information.

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 field list compensates well, and usage context is supplied. Gaps are minor: the maximum page depth (effectively a result cap) and cross-store ordering differences are only implicit in the schema.

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% and every parameter including enums and defaults is documented there. The only parameter-adjacent detail in the description, '50 per page', restates the page field's schema text, so there is no value added beyond the schema.

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?

States a specific verb and resource ('Fetch raw app reviews') plus scope ('unified schema across stores') and enumerates the returned fields, which separates it from mine_app_pain_points. An agent can distinguish it from all siblings 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?

'Use for drill-down after mine_app_pain_points' gives an explicit when-to-use and names the alternative it complements. It omits when-not-to-use (e.g. bulk collection, or that results are capped at 10 pages), so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds real value by saying it is an instant archive read with no LLM cost and by disclosing the default window and the degraded-fewer-than-two-snapshots behavior. It does not discuss permissions or rate limits, but those are implied by the read-only annotation.

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 short sentences, front-loaded with what is compared, then latency/cost, then default and edge case. No filler.

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-shape burden and does well: theme labels, percentage-point deltas, and the note case. It omits how many themes are returned or ordering, a minor gap for a comparison tool.

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 the schema already documents appId, from, to and store with examples. The description only adds the default from/to window, which is useful but does not go beyond what the schema's 'optional, default newest' already implies.

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?

Specific verb and resource: it compares two archived analyses and labels each theme new/resolved/rising/falling/stable. That clearly separates it from mine_app_pain_points (which produces the analyses) and from get_app_reviews, 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?

Gives the default comparison window (latest vs ~30 days earlier) and states what happens when the precondition fails ('fewer than two snapshots'), which is the key when-to-call context. It stops short of naming the sibling to use instead when there aren't two snapshots.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so safety is covered elsewhere. The description adds genuine interpretation context that the schema cannot: Android stats are aggregated from recent reviews while iOS reports the current version plus release notes — a caveat that materially affects how results should be read.

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 returns are front-loaded and every clause carries information; the platform-specific fragments are terse but purposeful. The telegraphic style is slightly dense but wastes no sentences.

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 must convey what comes back, and it names the three key metrics plus the per-platform aggregation behavior. An agent could call this correctly; only ordering/pagination and version-listing depth are unaddressed.

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%, and the schema itself explains appId formats, store inference, and the country default. The description adds nothing about parameters, which is acceptable given the schema does the work — baseline 3.

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?

States the resource precisely — per-version review stats with the three returned fields (review count, average rating, first/last seen) — so it's clearly distinct from get_app_reviews. It doesn't name a sibling explicitly, but the version-granularity scope makes the split obvious.

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 phrase 'spot a rating crash right after a bad release' gives a concrete use scenario, which is more than many tools offer. However, it never says when to prefer get_app_reviews or get_pain_trend instead, nor any exclusion criteria, so the routing decision is left to inference.

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

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

Beyond the readOnly/idempotent annotations, it discloses the 7-day cache, the 30-120s cold-run cost, and — critically — that results can come back with mode:"agent" requiring the caller to do the clustering itself. That conditional-response contract is exactly the kind of trait annotations cannot express.

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?

Front-loads the core purpose, then layers output shape, latency/caching, and the agent-mode caveat in a tight sequence. Every sentence carries distinct information with no repetition of schema content.

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?

There is no output schema, but the description fully covers the return shape (title, sharePercent, severity, verbatim quotes) and the alternate agent-mode payload with instructions. An agent knows both what it gets and what it may need to do next.

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 all seven parameters (appId, store inference, analyze modes, review tiers, maxRating) are already documented in full. The description adds no further parameter guidance, so the baseline 3 applies.

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?

States a precise verb chain (fetch reviews → filter negatives → cluster into ranked pain points) and enumerates the output fields. It is clearly distinguishable from the sibling get_app_reviews, which only fetches raw reviews.

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?

"Ideal for competitive research and product discovery" gives clear context, and the cold-vs-cached latency note plus the mode:"agent" fallback tells the agent what to expect and what extra work it may have to do. It stops short of explicitly naming when to prefer get_app_reviews or get_pain_trend instead.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description's main behavioral addition is the merged-by-default store behavior, which largely restates the schema's store default; nothing about result shape, ranking, or empty-result handling is added.

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?

Two tight sentences, with the sources and the usage rule front-loaded and zero filler. Every clause carries information.

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 small read-only lookup tool with fully described params and no output schema, the description gives enough to call it correctly, including the id-producing role that feeds the other tools. Minor gap: no hint about result shape or deduplication across stores.

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's only parameter-adjacent statement (

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?

States a specific verb ('search') and resource ('apps') plus the two sources covered (iOS App Store, Google Play) and the output value ('their ids'). It stops short of explicitly contrasting with siblings, though 'find apps and their ids' implicitly positions it upstream of get_app_details.

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?

'Use this FIRST when you only know an app name or a category' is a clear routing rule that implies the id-dependent siblings should be called later. No explicit when-not or named alternative tool, so not a 5.

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

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

Annotations already cover safety (non-readOnly, openWorld, idempotent, non-destructive), and the description adds useful behavioral context: plan quotas, digest contents limited to NEW 1-2★ reviews and NEW/RISING pain points, and supported alert destinations. It does not clarify what 'test' does or whether removing an app also removes the webhook.

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?

Front-loads the core purpose and is compact, though the parenthetical plan limits and the final action list make it slightly dense. Every sentence contributes useful information; there is no filler.

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?

Given a multi-action tool with no output schema, the description covers purpose, plan limits, digest behavior, and alert destinations well. Minor gaps remain around what 'list' returns and what 'test' performs, but an agent can call the tool correctly for most actions.

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?

The schema already documents appId, store inference, and webhookUrl with 75% description coverage. The description adds the action enum and ties webhookUrl to Slack/Discord/webhook destinations, but does not explain what each action does (e.g., 'test') or how parameters map to actions beyond the schema.

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?

States a specific verb and resource ('continuous competitor monitoring', 'manage the watchlist and the alert destination') and clearly separates itself from the sibling retrieval/analytics tools by emphasizing ongoing alerts rather than on-demand data.

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?

Provides clear context for when this tool is appropriate (ongoing monitoring with pushed digests) and includes plan tiers that constrain usage, but does not explicitly say when not to use it or name alternate siblings for one-off lookups.

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