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

Annotations already mark this readOnly, non-destructive, and non-open-world, but the description adds meaningful behavior: diagnostics only, no network request made, and secrets are never returned. These are the exact assurances an agent needs before dumping output to a user, and they go beyond the structured hints.

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 reported, then the no-network/no-secrets guarantees, then the trigger condition. Every sentence carries information and none repeats the title or name.

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 present, the description correctly compensates by enumerating the returned fields (credential kinds loaded, active site, timeout, configuration problems). Combined with the safety notes, an agent has everything needed to call and interpret this zero-arg diagnostic.

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 tool takes zero parameters, so there is no per-parameter semantics to document; the baseline of 4 applies. The empty schema is consistent with the description's framing of a no-argument status probe.

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 (Report) plus the exact resource (AGC credential configuration) and enumerates the reported fields: credential kinds, active site, timeout, and configuration problems. This cleanly separates it from the data-fetching siblings like agc_list_apps and agc_report_export.

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 trigger: 'Call this first when requests start failing with auth errors.' That is clear context for invocation, though it stops short of naming when not to use it or pointing to which sibling to try next after a clean result.

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 readOnlyHint/openWorldHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the normalised row shape, the degraded fallback response behavior when the gateway rejects the body, and the community-verified/schema-drift warning.

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 purpose then fallback behavior then reliability caveat. Dense but every sentence carries information; 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 compensates by naming the return fields {day, version, count, users, rate}, and it flags the unreliable-response path. An agent has enough to call it correctly, though the sibling-selection gap and absence of pagination/date-range default semantics leave a small hole.

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 all 7 parameters including enums and date formats. The description adds little parameter-level meaning beyond noting the dimension-driven row shape, so 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 verb (Query) and resource (AGC APM crash/app-freeze metrics) and names the exact endpoint, plus the shape of returned rows. An agent can distinguish this metric-query tool from siblings like agc_crash_summary 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?

Provides one real routing hint: if the gateway rejects the body shape, fall back to agc_request to adjust fields. However, it never states when to choose this tool versus agc_crash_summary or agc_report_trend, which is the primary selection ambiguity for an agent.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description adds real behavioral value by disclosing that results are pre-aggregated into total, week-over-week comparison, worst days, top versions and a daily series. It omits any note about authentication requirements or query cost/limits, which would be the remaining useful disclosures.

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?

A single front-loaded sentence with the action first and the output list after; no filler or repetition. The colon-separated enumeration is dense but readable.

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 present, the description carries the burden of describing returns and does so explicitly (total, WoW, worst days, versions, daily series). Parameters are fully covered by the schema, but default date behavior and auth expectations are left unstated for a 7-parameter 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 description coverage is 100%, so every parameter including enums (kind, site, dimension) is already documented, and the baseline is 3. The description adds only a faint hint about a 7-day comparison window (implying date defaults), but does not explain the interaction between startDate/endDate and the WoW 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?

Names a specific verb+resource ('Query crash or app-freeze metrics and summarise') and enumerates the exact outputs (total, WoW, worst days, top versions, daily series), which is far more informative than the title alone. It doesn't explicitly differentiate itself from close siblings like agc_crash_metric or agc_report_trend, so an agent must infer the boundary from the word 'summarise'.

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 prefer this over agc_crash_metric, agc_report_trend, or agc_daily_report, and no prerequisites or exclusions. The only usage-adjacent hints are the schema defaults ('default crash', default site), which the description doesn't restate.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower, yet the description still adds real behavior: each section degrades independently into a marked paragraph, and output is Markdown returned inline plus optionally persisted to outPath. One subtlety remains unaddressed — a file write side effect sits in slight tension with readOnlyHint, mitigated only by the optional outPath/overwrite parameters.

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 dense sentences with zero filler, front-loading what the report contains, then the degradation and output behavior. 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 9 parameters, no output schema and rich annotations, the description is nearly sufficient: content, defaults, failure behavior and output destination are all covered. Auth/prerequisite context and the overwrite semantics are left to 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 coverage is 89%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it explains that the 'report' enum drives the download/install section and ties platform/countries to the 'review snapshot', which is helpful given the opaque enum values.

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 ('Build a daily operations digest for one day') and enumerates exactly what the digest contains (7-day download/install trend, crash/app-freeze totals, review snapshot). This clearly separates it from agc_weekly_report by time window, though it never names the sibling explicitly.

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 description establishes context (a single-day consolidated digest, default yesterday) and that outPath writing is optional, giving implied usage. But it never states when to prefer this composite report over the granular siblings (agc_report_trend, agc_crash_summary, agc_reviews_list) or any exclusion.

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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered structurally. The description usefully adds the batch behavior (comma-separated input, up to 50 names, potentially multiple appIds returned). It does not disclose what happens when a package name is unknown or unmatched, which for an open-world lookup is a meaningful gap.

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?

A single front-loaded sentence with no filler. The batch constraint sits right where an agent needs it, and nothing is restated wastefully.

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 simple read-only resolver with no output schema, the description covers the input shape and cap but says nothing about the response shape or behavior on unmatched packages. Since no output schema exists to carry that burden, a brief note on the returned mapping would have made it complete.

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, including the site enum and its AGC_SITE default. The description only reinforces the comma-separated format and the 50-item limit for packageNames, adding marginal value over the schema. Baseline 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?

States a specific verb and resource: 'Resolve AGC appId(s) from package name(s)'. This clearly distinguishes it from siblings like agc_list_apps or agc_get_app_id-style lookups, since the transformation from package name to appId is explicit. It stops short of naming a sibling alternative, but the purpose 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as agc_list_apps for enumerating apps. The only contextual hint is the 50-item batch cap, which is a constraint rather than a usage rule. An agent must infer when this tool is preferable to its siblings.

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 readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful scope information (results span all projects visible to the credential), but says nothing about credential requirements beyond visibility, rate limits, or result volume. Modest value on top of annotations.

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: the first declares what is listed and the fields returned, the second states the tool's role. No filler, and the core scope is front-loaded.

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 and a single optional parameter, the description usefully compensates by enumerating the returned fields and by explaining the credential-relative scope. The only gap is that the `site` selector's effect on results is left entirely to 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?

There is one optional `site` parameter with 100% schema description coverage including the enum values and the AGC_SITE default, so the schema fully documents it. The description adds no semantics about the site parameter, which is the expected baseline when the schema does the heavy lifting.

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 (list AGC projects and the apps inside each) and even enumerates the per-app fields returned (appId, name, package name, device types). It doesn't explicitly differentiate itself from the overlapping sibling `agc_get_app_id`, which also surfaces an appId, so it falls short of a top score.

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 to discover the appId every other tool requires" gives a clear usage context and effectively positions it as the entry-point tool. It stops short of naming alternatives or stating when-not-to-use (e.g. when you already know the appId and only need `agc_get_app_id`).

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the safety bar is met. The description adds two non-obvious behaviors the annotations do not cover: the 6-month maximum window and the API-client credential prerequisite. Rate limits and result volume remain unstated.

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, no filler, with the returned data shape and the window constraint front-loaded. Every clause carries information an agent needs.

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 compensates by naming the returned metrics (average, star histogram). Combined with the credential prerequisite and window cap, an agent has enough to call it correctly, though nothing explains pagination or aggregation granularity.

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 begin/end, site, platform, countries and appId are all documented in the schema; baseline is 3. The description's 'max 6 months' loosely constrains the begin/end pair but adds no format or default detail beyond what the schema already provides.

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 ratings for an app') and enumerates the shape of the result (average, star histogram), which separates it from review-oriented siblings like agc_reviews_list. It does not name an alternative sibling explicitly, so it stops short of the top band.

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 operative constraints (time window capped at 6 months, requires the API-client credential), which tells the agent when the tool is callable. It never says when to prefer this over agc_reviews_list, agc_review_insights, or agc_report_trend, so routing 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?

Annotations already declare readOnly=true, openWorld=true, destructive=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond that: the 180-day window cap, the row cap with allRows=false default, and that outPath writes a raw CSV alongside the parsed rows.

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?

Purpose and output are front-loaded in the first sentence; the long report enumeration earns its space by disambiguating the report parameter, and the trailing constraints (window, cap, outPath) are compact and information-dense.

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 12-param tool with no output schema, the description covers the return shape (parsed rows plus optional CSV), the window limit, and the row cap. It does not elaborate on filters/groupBy interaction or report-specific extraQuery, though the schema carries descriptions for those.

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 real value beyond the schema by defining what each report enum member actually contains (e.g. harmony-download vs install-failed) and clarifying the window/cap semantics for allRows and outPath.

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 (export) and resource (AGC operations report) with the output form (parsed rows). The 16-item report enumeration makes the tool's scope unambiguous, though it never explicitly distinguishes itself from sibling report tools like agc_daily_report or agc_report_trend.

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 report list and the 180-day window note imply when this tool applies, but there is no explicit when-to-use vs alternatives guidance against the many sibling report tools (agc_daily_report, agc_weekly_report, agc_report_trend). Usage must be inferred.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the analytical outputs the agent will receive, which is helpful, but it never clarifies whether 'export' writes a file, what the date window actually covers, or any rate/permission constraints.

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, front-loaded with the core action and followed by the overview tip. Every clause carries information; no filler or restated name/title.

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 9-parameter tool with an undocumented nested 'filters' object and no output schema, the description does partially compensate by describing the returned trend components. However, it leaves the filters structure, groupBy behavior, and site/language effects unexplained, so it is adequate rather than complete.

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 56%, and the description only elaborates on 'metric' (substring match, empty for overview) — semantics already present in the schema. The undocumented 'filters' nested object, 'groupBy', 'site', and date defaults get no additional explanation in the 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 specific verbs (export + analyse) and resource (an AGC report metric), and enumerates exactly what is computed: WoW change, 7-day moving average direction, z-score anomaly days, peak/trough, 28-day sparkline. It does not explicitly name the sibling it differs from (agc_report_export, agc_daily_report, agc_weekly_report), so an agent must infer the boundary.

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 one useful invocation tip — use metric="" for a compact overview of all numeric columns — which is genuinely actionable. But it offers no when-to-use guidance relative to agc_report_export or the daily/weekly report tools, nor any prerequisites or date-range considerations.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), yet the description adds genuinely new behavior: the exact allowlisted path prefixes, the fact that review/app-info paths are GET-only, and that publish/upload/reply/delete are structurally blocked. It omits auth requirements, rate limits, and error behavior, so not a 5.

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 tool's role before the path list, and every sentence carries a constraint an agent needs. The long comma-separated allowlist is verbose but functional rather than filler, so no sentence is wasted.

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, a brief note on response shape or error signaling would help, and auth prerequisites are unstated. However, for a passthrough whose returns are endpoint-dependent, the description covers the critical call-correctness constraints (allowed paths, method restrictions, blocked writes) adequately.

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 goes beyond the schema by coupling the method parameter to specific path families ('review/app-info paths accept GET only'), which is real semantic value the schema's plain GET/POST enum does not convey.

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 ('Generic GET/POST passthrough for AGC Connect API read endpoints') and immediately scopes it as the fallback for endpoints 'without a dedicated tool', which cleanly separates it from the twelve dedicated agc_* siblings. An agent can tell what it is and when it is the right choice 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 phrase 'without a dedicated tool' gives clear selection context relative to siblings, and the enumerated path prefixes define the usable scope. It never names a specific sibling tool to prefer instead, and gives no exclusion beyond the write-operation note, so it stops short of fully explicit routing.

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 cover the safety profile (readOnly, non-destructive, open-world). The description adds operationally relevant detail beyond that: the fetch ceiling (up to 10 pages of 100 reviews), the credential requirement, and the linkage between onlyNegative and minRating's default ceiling of 3.

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 action, then the outputs, then the key parameter switch and prerequisite. Three compact sentences with essentially no filler; only the parenthetical keyword-method note is arguably extra.

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 aggregation tool with full schema coverage and no output schema, the description names what is produced and covers the auth prerequisite and the main filtering toggle. Minor gap: no mention of how results scale with pages/topN or any rate/limit behavior beyond the page cap.

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 already 100%, so the baseline is 3, but the description adds real meaning the schema omits: it explains that onlyNegative filters to stars ≤ minRating with a default ceiling of 3, and that 'pages' means pages of 100 reviews. The interaction between onlyNegative and minRating is not spelled out 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 verb ('Fetch reviews') plus a concrete analysis outcome list: star histogram, average rating, CJK/Latin keyword clusters, and per-version negative hotspots. This clearly separates it from the raw-listing sibling agc_reviews_list and the aggregate agc_ratings_summary.

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 conditional guidance for one parameter ('Set onlyNegative=true to focus on stars ≤ minRating') and a prerequisite ('Requires the API-client credential'), but never states when to choose this over the sibling agc_reviews_list or agc_ratings_summary. Usage is implied by the analysis framing rather than declared.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: a 6-month maximum window, a 100-item page cap, and the requirement for an API-client credential. It omits any pagination-walkthrough or rate-limit detail, keeping it out of the 5 range.

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?

A single dense sentence that front-loads the core action and pushes constraints to the clause after the dash. Nothing is redundant, though the filter parenthetical partially duplicates what the schema already lists.

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 read-only list tool with no output schema, the description covers the essentials: scope, filter surface, credential prerequisite and two hard limits. It does not describe return shape or how to page through results, but with readOnly annotations carrying the safety profile and a fully documented schema, the remaining gap is minor.

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 every one of the 13 parameters is already documented in the schema, including enum meanings for sort, site and platform. The description only recaps the filter categories and restates the two numeric caps, adding little syntax or format information beyond the schema baseline.

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 the review list') and enumerates the filter dimensions, which cleanly separates it from siblings like agc_ratings_summary and agc_review_insights. It stops short of explicitly naming those siblings, so it does not reach the top of the scale.

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 hard constraints (6-month window, page size max 100, API-client credential) that shape how the call must be made, but never says when to prefer this tool over agc_review_insights or agc_ratings_summary. Usage is implied by the tool's nature rather than stated.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds two genuinely useful facts beyond that: the previous week is fetched automatically (an extra round trip the caller should expect) and Markdown is optionally written to outPath, a local side effect worth flagging. It says nothing about auth requirements, latency from the multi-report aggregation, or failure modes.

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 with the purpose and time window front-loaded, followed by output content and the optional write. No filler; the only slight inefficiency is that defaults already documented in the schema are restated.

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 nine parameters, 44% coverage, and no output schema, the description does meaningful work: it names the three returned sections, states the returned format (Markdown), explains the automatic prior-week fetch, and covers the outPath side effect. Remaining gaps are crashKind, countries, and overwrite, which an agent must infer from 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 only 44%, so the description must compensate, and it partially does: it explains the date window semantics of endDate and the optional write behavior of outPath, and its section list hints at the report/crashKind/platform roles. But site, countries, overwrite, and the wide report enum are left for the schema alone, leaving a real gap.

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 ('Build a weekly digest') plus exact scope: the 7 days ending on endDate, with three named sections (download/install totals, crash totals, review keywords). 'Weekly' implicitly distinguishes it from the sibling agc_daily_report, but no sibling is named explicitly, so it falls short of full differentiation.

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 operating context: the 7-day window ends on endDate (default yesterday) and the previous week is fetched automatically for the WoW comparison. However it never states when to prefer this over agc_daily_report, agc_report_trend, or agc_report_export, so the routing guidance is only implied rather than explicit.

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