Review Expert

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds the non-obvious behavioral fact that this 'Never posts it: a person sends it from the app' — a publish-vs-save distinction the annotations do not convey. It stops short of covering idempotency (duplicate drafts on repeat calls) or auth requirements, so it is strong but not exhaustive.

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, front-loaded with what it does and the critical 'never posts' caveat before the alternative and example. Every sentence earns its place; the example is short and directly usable.

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?

An output schema exists, so return values need no explanation, and the description covers the key behavioral concern (no publishing) plus routing to the alternative. It omits auth/permission expectations and what happens on repeated saves, which would complete the picture for a non-idempotent write.

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 both parameters are already documented, and the baseline is 3. The inline example illustrates the shape and how review_id pairs with text, but adds no constraint semantics (e.g. the 5970-char limit) 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?

The description gives a specific verb and resource ('Saves reply text ... as a draft on one review') and explicitly scopes it to drafts rather than published replies. It also names the distinction against siblings draft_reply (AI-written) and implicitly post_reply, so an agent can identify the tool without opening a 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?

It states when to use this tool ('reply text you wrote (or the user dictated)') and when not to, explicitly routing to draft_reply 'if you want Review Expert to write the reply.' The alternative is named with the condition that selects it, leaving nothing 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds real context beyond them: the deletion is irreversible ('Cannot be undone') and the blast radius excludes posted replies. Remaining gaps (auth requirements) are minor.

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 tight sentences front-loaded with the action, followed by scope limits, irreversibility, and a concrete call example. Nothing is redundant or padding.

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 single-parameter destructive delete with an output schema available, the description covers what an agent needs: what is deleted, what is never affected, irreversibility, and valid id sources. Return values need not be explained given the output 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 the single draft_id parameter is fully documented including UUID format. The description repeats the same sourcing hint and adds a usage example, but adds no semantic detail the schema lacks; 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?

Specific verb+resource ('Deletes one unsent reply draft'), with scope narrowed to unsent drafts only. It explicitly contrasts with the sibling post_reply path by stating replies already posted to a store are never touched, so an agent can distinguish it from post_reply and list_drafts without opening a 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?

It tells the agent where draft_ids come from (list_drafts, draft_reply, create_reply_draft) and restricts applicability to drafts, which is clear usage context. It stops short of an explicit 'use this when / use X instead when' rule, but the boundary is unambiguous.

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?

The description adds substantial behavior beyond the annotations: it saves a draft but never posts, generates one AI reply per team call, takes about 10–15 seconds, and defines what setup_required and syncing mean for the user. This is exactly the kind of operational and side-effect detail an agent needs before invoking the tool.

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 purpose and safety guarantee are front-loaded, followed by latency, an example, and actionable error-state handling. Every sentence earns its place and no context is buried.

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 the tool's complexity, the annotations, and the output schema, the description covers what the tool does, its non-posting safety profile, expected latency, and error-state behavior. An agent has enough to call it correctly without needing more.

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 input schema already documents tone, review_id, and instructions. The description's example mirrors those same fields without adding syntax or semantics beyond the schema, so the baseline of 3 is appropriate.

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 states a specific verb and resource: 'Generates an AI reply draft for one review and saves it as a draft.' It distinguishes the write-as-draft behavior from posting ('Never posts it'), but it does not explicitly name or contrast the sibling create_reply_draft tool.

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?

It gives clear operational context: use this for one review, save as a draft, and a person sends it later in the app. It also explains the setup_required and syncing states, though it does not explicitly say when to choose this over create_reply_draft or other reply tools.

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?

Goes well beyond the readOnly/idempotent annotations by documenting ordering, pagination, untrusted third-party text fields, and two important non-success states: setup_required and syncing. The setup_required guidance is especially valuable because it prevents misreporting zero reviews.

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 what the tool returns, then usage, alternative routing, safety guidance, and error-state handling. Despite covering many concerns, it stays dense and purposeful with 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 the tool's complexity, the description is complete enough for correct invocation: it covers scope, ordering, filters, pagination, alternative tools, untrusted content, and sync/setup edge cases. The output schema can handle return-value details without needing description support.

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 already 100%, so the baseline is 3. The description adds value with an example showing how app_id, rating, and has_reply combine for unanswered negative reviews, though most individual parameter semantics remain in 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 resource and scope: reviews of one app, newest first, with cursor pagination. It also names and routes away from search_reviews, so an agent can distinguish the two tools 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.

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

Explicitly says to use this for recent feedback on a specific app, identifies period, rating, and has_reply as filters, and names search_reviews as the alternative for text search. The example clarifies a practical combined-filter use case.

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, and the description adds substantive behavior beyond that: it discloses the untrusted-text fields (title, body, author_name, reply) as a prompt-injection guard, and explains two non-obvious states — setup_required (no app connected, don't report zero reviews) and syncing (first sync still running) — with prescribed agent handling.

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-loaded with what it returns, followed by the use case, an example, and two error-handling rules. Every sentence carries operational value; nothing is restated from the schema or annotations.

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?

Output schema exists so return fields needn't be enumerated, yet the description flags the untrusted ones for safety. Combined with error-state guidance and id provenance, an agent has everything needed to call it correctly and interpret failures.

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% and the single parameter is already fully documented and format-constrained, so the baseline is a 3. The description adds a concrete example payload and reinforces provenance ('<id from get_app_reviews>'), giving a modest lift.

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 with scope: fetches ONE review by id, including its posted developer reply. The 'one review by id' framing implicitly separates it from list/search siblings like get_app_reviews and search_reviews, though it never names them as alternatives for retrieval.

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 a concrete use case ('show the full text before drafting a reply'), tying it to draft_reply, and points at get_app_reviews as the id source. No explicit when-not-to-use clause, but the context is clear enough to route correctly.

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 the safety profile (readOnly, idempotent, non-destructive), and the description goes further by disclosing the two non-obvious states: setup_required (no store app connected, tell the user to open the error link, do not report zero reviews) and syncing (first sync in progress). That state-handling guidance is exactly the context annotations cannot convey.

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-loaded with the purpose, then the call-ordering rule, then the filter example, then edge-case states. Every sentence carries distinct information with no repetition of the schema or annotations.

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?

An output schema exists, so return-value documentation is not required, yet the description still names the key fields an agent needs to chain calls. Error and in-progress states are both covered, leaving nothing an agent needs missing for a single-optional-param read 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% and the enum is already documented, so the baseline is 3. The description adds a small but real clarification — that {"platform": "google_play"} means Android apps only — which maps the enum value to a human-meaningful concept.

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 ('Lists the App Store and Google Play apps connected to your Review Expert team') and enumerates the returned fields (id, name, platform, store id, last sync). It also implicitly distinguishes itself from siblings like get_app_reviews, which require the id this tool returns.

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?

Explicitly says 'Call this first: other tools take the returned id as app_id', which is a direct when-to-use rule tied to the sibling tools. It also gives a concrete filtering example and prescribes behavior for the setup_required and syncing states.

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 the safe-read profile, yet the description adds substantial context: setup_required means no store app is connected (tell the user to open the error link, don't report zero reviews) and syncing means first sync is running. It also flags that draft text may quote untrusted review text — a prompt-injection warning beyond any structured field.

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-loaded with what the tool returns, then use cases, an example payload, and error-state semantics — each sentence carries distinct information with 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?

Output schema exists so return values need no explanation; the description still covers pagination via next_cursor, downstream draft_id usage, and the setup_required/syncing states. Nothing needed to call it correctly is missing.

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 limit, app_id and cursor are already documented. The description only adds a worked example, not syntax or filtering semantics beyond the schema. 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 specific resource with useful qualifiers: unsent reply drafts, AI or hand-written, ordered newest first, in Review Expert. An agent can distinguish it from review-reading siblings like get_app_reviews. It does not name an explicit alternative, but the resource is unambiguous.

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?

Explicitly says to use it to review pending drafts or to obtain a draft_id for delete_draft, which routes the agent to the right downstream tool. No when-not-to-use exclusions, but the use context is clear.

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?

Adds substantial context beyond annotations: the reply is public and visible to the reviewer, it replaces any existing reply (consistent with destructiveHint=true and non-idempotent), and a specific scope is required. These are exactly the consequences an agent needs before a destructive open-world write.

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 compact sentences, front-loaded with what the tool does, followed by impact and the confirmation guardrail. 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 rich annotations and an output schema, the description covers everything material: publication target, public visibility, replacement of prior content, auth scope, and the human-confirmation requirement.

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 both parameters are documented, and the description adds a meaningful constraint by tying `text` to the exact user-approved string. Minor added value only, since review_id sourcing is already in the schema description.

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 ("Publishes a developer reply") and scopes it to App Store or Google Play. It also discloses the replace-existing-reply behavior, which distinguishes it from the draft-oriented siblings.

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 clear preconditions: requires the replies:post scope and requires showing the user the exact text with explicit confirmation first. It does not explicitly name draft_reply/create_reply_draft as the non-publishing alternative, so sibling routing is left slightly 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?

Annotations already declare a safe idempotent read, so the description focuses elsewhere and adds genuine context: the change metric is computed against a previous period of equal length, response time is measured in hours from review to posted reply, and by_platform only lists stores the selected apps actually occupy. The setup_required/syncing guidance ('do not report zero reviews') is real behavioral disclosure that prevents a damaging misinterpretation.

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-loaded with the purpose and metric list, then scope, then usage cue, then error-state handling — a sensible ordering with no filler sentences. It is dense and near the upper end of comfortable length, and the dangling by_platform clause is wasted text.

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?

An output schema exists, so return values needn't be explained, and the description still helpfully previews what is aggregated plus the defaults inherited from the schema. Error-state and empty-data handling are covered. The only material gap is the reference to by_platform, which is absent from the schema and could send an agent looking for a parameter that isn't there.

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%, with defaults for since, until and app_id already documented, so the baseline applies. The description contributes a concrete example value for the timestamp format, but it also references a 'by_platform' parameter that does not appear in the input schema, which muddies rather than clarifies parameter behavior.

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 with a specific verb and resource ('Aggregate numbers for a period') and then enumerates the exact metrics returned: totals, period-over-period change, average rating, star distribution, response rate and response time. The scope ('for one app or all apps') is stated, which cleanly separates it from the row-level siblings get_app_reviews and get_review.

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 it for summaries and reports' gives the agent a positive selection cue against the list-style sibling tools. It also handles the two branch conditions an agent will actually hit (setup_required, syncing) with explicit instructions. It stops short of naming an alternative tool or stating when-not to use it.

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?

Well beyond the readOnly/idempotent annotations, it discloses matching semantics (all words must appear, case-insensitive), result ordering (newest first), and the untrusted-third-party status of title/body/author_name/reply with an instruction to treat them as data only — a genuine prompt-injection safeguard. It also warns that a setup_required response must not be reported as zero reviews.

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 what it searches and its scope, then the alternative, then safety and error-state notes. Every sentence carries distinct operational value; nothing restates the name or the annotations.

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?

Output schema covers return shape and pagination, so the description correctly omits them and spends its budget on matching semantics, routing, and failure states. For a 9-parameter read tool this is sufficient to call it correctly on the first try.

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 carries parameter documentation and the baseline applies. The description still adds meaning: query is AND-of-words and case-insensitive, and app_ids/platform act as scope narrowing rather than required filters. It does not elaborate on combining rating with has_reply or time-window interaction, which the schema leaves implicit.

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 (full-text search) and resource (review bodies) plus scope (all apps, or narrowed by app_ids/platform). It explicitly contrasts with get_app_reviews, so an agent can route between them without opening schemas.

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 an explicit when-to-use with a concrete example call, and names an alternative (get_app_reviews) with the condition that selects it (browsing one app without a query). It also prescribes agent behavior for two non-result states (setup_required, syncing).

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds behavior those annotations cannot express: the setup_required error means no app is connected and the agent must surface the link rather than report zero reviews, and syncing means the first sync is still running. The "do not report zero reviews" guardrail directly prevents a serious misinterpretation of results.

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-loaded with what the tool returns, followed by usage, a compact example, and error-state handling in two short clauses. No filler sentences; each one conveys distinct 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?

An output schema exists, so return shape need not be explained. Given four optional parameters with defaults, the description covers the derivation of sentiment, a usage scenario, an example, and the two non-obvious error states — everything an agent needs to call and interpret it correctly.

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 parameters are already documented with formats and defaults; the description adds the semantic that sentiment buckets are derived from star ratings (4-5/3/1-2) and shows a working payload with interval and since. That goes beyond the schema's "Bucket size." without duplicating it.

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+resource: review counts split into positive/neutral/negative buckets plus average rating, bucketed per day/week/month. It also clarifies that sentiment is derived from the star rating, which removes ambiguity about how the classification is produced. It does not explicitly distinguish itself from the sibling review_stats, which is the main thing keeping it from 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?

"Use it to spot when ratings changed, e.g. after a release" gives a concrete usage context, and the embedded example call shows a realistic invocation. It stops short of naming an alternative (e.g. review_stats) or stating when not to use it, so the routing guidance is clear but not complete.

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