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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so safety is covered. The description adds genuine behavioral context beyond that: results are impression-weighted, spend-heavy low scorers are named, and it identifies the root-cause component. It does not cover cost, latency, or what the 'named keywords' set contains at summary vs full detail.

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 first two sentences are dense and front-loaded with the highest-value information: components, weighting, and the diagnostic payoff. Minor waste remains — 'Read-only' duplicates readOnlyHint, and 'Tools revision: d80f65c0.' carries no selection or invocation value for an agent.

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 explanation is not required, and the description adequately frames the analysis. However, for a tool with six parameters at zero schema coverage, it leaves the temporal window, grouping granularity, and finding-limit behavior undefined, which are choices an agent must make blindly.

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 0% across 6 parameters, so the description carries the full burden and mostly drops it. The enum params (group_by, detail, render) are self-explanatory by value name, but the description never explains the `days` lookback window, `max_findings` (which governs how many 'worst-scoring keywords' are named), or how `customer_id` scopes the call.

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

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

The description names a specific verb and resource (break Quality Score into three named components) and adds scope detail: impression-weighted, worst high-spend keywords surfaced, and which component is dragging the account. An agent can tell it apart from generic diagnostics like account_health_score or full_audit by the QS focus, though no sibling is named 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?

Usage is implied rather than stated: 'says which component is dragging the account down' signals a diagnostic scenario, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as full_audit or account_health_score that also cover account diagnostics. The agent must infer the routing.

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