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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it specifies time windows (last 7 days, days=7|14|30), result limits (top 50), and the bundling of campaign budget loss into a synthetic field. It also explains the 'raw' action for custom GAQL SELECT. However, it doesn't disclose potential rate limits, pagination behavior, or what happens when no data is available, but given the annotations cover the core safety aspects, this is a strong score.

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 dense but well-structured: it starts with a high-level summary, then lists actions with examples, and ends with bulk support. It's front-loaded with the most important info (purpose and actions). However, it's somewhat long and could be trimmed without losing value (e.g., the parenthetical examples are helpful but could be shortened). The use of backticks and clear action names aids readability. Overall, it's efficient but not perfectly concise.

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 (9 parameters, multiple actions, no output schema), the description is quite complete. It covers the main actions, their outputs (e.g., 'approval_status, system_serving_status'), and the reasoning behind the design (budget as campaign property). It also mentions bulk support and time windows. However, it doesn't describe the return format or how to interpret the 'raw' output, and it doesn't explicitly state that the tool is read-only (though annotations cover that). For a tool with no output schema, this is a strong description, but a perfect score would require more detail on output structure and edge cases.

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%, so the description must compensate. It does: it explains that 'account' and 'customer_id' are used for scope, and that 'days' accepts 7|14|30 for diagnostics. It also mentions bulk parameters (campaign_ids, ad_group_ids, customer_ids) and the 'query' parameter for raw GAQL SELECT. However, it doesn't explicitly map each parameter to its purpose (e.g., what 'ad_group_id' vs 'ad_group_ids' do differently), and the 'query' parameter is only implied via 'custom GAQL SELECT'. Still, the description provides enough context for an agent to infer parameter usage, so a 4 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 clearly states the tool's purpose: 'Keyword analytics, search terms, status/policy diagnostics, auction diagnostics, or custom GAQL SELECT.' It enumerates specific actions (keywords, search_terms, status, diagnostics, raw) with concrete examples (e.g., 'RARELY_SERVED for Low search volume'), distinguishing it from sibling tools like google_ads_keywords_diagnostics and google_ads_keywords_raw by noting that this tool bundles those actions under one interface. The verb 'analytics' and resource 'keywords' are specific, and the scope ('Uses account + customer_id') is explicit.

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 provides explicit when-to-use guidance: it answers questions like 'why is my keyword not serving?' for status, and 'is it bid or Quality Score?' for diagnostics. It also explains the difference between actions (e.g., 'bundles per-campaign budget-loss as _campaign_budget_loss since budget is a campaign property, not keyword') and notes bulk support for campaign_ids, ad_group_ids, customer_ids. While it doesn't explicitly say 'use this instead of X', the action list and examples make it clear when to use this tool versus the specialized siblings (e.g., google_ads_keywords_diagnostics, google_ads_keywords_raw).

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