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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it uses account+customer_id for scope, supports bulk execution, and for diagnostics includes day range and campaign budget loss. However, it does not disclose the output format or any additional behavioral traits for the raw action beyond saying it accepts any GAQL SELECT. Since annotations cover the safety profile, the description adds some but not rich behavioral context.

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 long and covers multiple actions, which is unnecessary for a tool named 'raw'. It front-loads a laundry list of actions, then provides detailed explanations for each, including examples. This is over-specified and dilutes the focus. A concise description for the raw action (custom GAQL) would suffice, with a note that other actions are available in sibling tools.

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 params, no output schema, no parameter descriptions), the description is incomplete. It does not explain what raw GAQL SELECT returns, how to construct a valid query, or provide examples. It also doesn't cover all parameters or indicate which are required for different actions. The description is not enough for an agent to correctly invoke the tool, especially for the raw action.

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 schema description coverage at 0%, the description must explain all 9 parameters, but it only partially does. It mentions account and customer_id for scope, campaign_id/ad_group_id filters for diagnostics, and days=7|14|30 in diagnostics. However, it does not clarify the 'query' parameter (beyond saying raw accepts any GAQL SELECT), nor the plural IDs (campaign_ids etc.) beyond bulk support. The description is not sufficient to understand how to use all parameters effectively.

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 lists many actions (keywords, search_terms, status, diagnostics, raw) but the tool name and '[Flattened action: raw]' indicate its primary purpose is custom GAQL SELECT. It does state 'custom GAQL SELECT' as one of the actions, but the rest of the description confuses the scope by detailing all actions. It is not a tautology but lacks focus on the raw action specifically.

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 explicit guidance on when to use this tool versus the sibling tools (e.g., google_ads_keywords_diagnostics, google_ads_keywords_keywords). The description mentions actions but does not say 'use this for raw queries only' or 'for other actions use the dedicated tools'. The bulk support is mentioned but not tied to a specific use case. This leaves the agent without clear decision guidance.

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