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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description has a lower burden. It adds useful context about output granularity (per keyword per day), the 1–10 Quality Score scale, and the three component classifications, though it does not cover pagination or how limit truncates 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?

The description is front-loaded with the core purpose and then layers in usage, return details, the alternative sibling, and safety in a logical order. It is slightly long and includes some redundancy — notably the read-only statement already covered by annotations and return details already present in the output schema — but every sentence is purposeful.

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 report tool with an output schema and rich annotations, the description covers purpose, usage, alternative routing, and key output semantics, so an agent is well equipped to invoke it. It falls short of 5 only because the limit parameter's behavior is left unstated and some returned-field detail duplicates 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?

With 0% schema description coverage, the description must compensate, and it does partially by defining days as the lookback window and ad_group_id as a scoping filter recommended for large accounts. However, limit and customer_id receive no semantic explanation beyond the schema's bare names and defaults, leaving clear gaps for a 4-parameter tool.

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 — a Google Ads keyword QUALITY SCORE report over time — and frames the exact diagnostic question it answers (when a score dropped and which component caused it). It explicitly distinguishes itself from the current-snapshot sibling list_entities(entity='keywords'), so an agent can route correctly 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?

It states the diagnostic use case, recommends ad_group_id scoping on large accounts, and names the alternative historical-vs-current view with the sibling that supplies the current snapshot. The condition that selects between this and list_entities is made explicit rather than left to inference.

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