google_ads_performance_analyze

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Read-only,' explains failure behavior ('Any subcomponent that fails is replaced with the string 'Retrieval failed' rather than aborting'), details default period, and specifies optional return fields (e.g., cpa_current? only when conversions > 0). This is thorough and transparent beyond the schema.

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-organized, starting with purpose, then return shape, failure handling, and alternatives. While it's a single paragraph, each sentence adds essential information, and the return shape is packed into a concise structure. Slight deduction for lack of formatting (e.g., bullets) but overall efficient.

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 that there is no output schema, the description comprehensively documents the entire return shape, including nested objects, optional fields, and conditions. It also explains error recovery behavior, period defaults, and tool alternatives. This is complete for a complex analysis tool with no structured output definition.

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 baseline is 3. The tool description adds no new parameter meaning beyond what the schema already contains—e.g., the 'tuned for short-horizon comparison' note appears verbatim in the schema's period description. The description simply restates schema details rather than enriching them, so no score above 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?

The description clearly states the tool's purpose with a specific verb 'Diagnose' and a single resource ('a single Google Ads campaign'), and enumerates the composed components (current-vs-previous comparison, top search terms, Google recommendations, recent change history). It also distinguishes itself from sibling tools by naming alternatives for different use cases, ensuring no ambiguity.

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?

Explicit usage guidance is provided by defaulting to LAST_7_DAYS and recommending longer baselines for extended comparison. Moreover, it clearly states when to use alternative tools: 'For cost-spike root-cause analysis use google_ads_cost_increase_investigate; for account-wide health use google_ads_health_check_all.' This is direct when-to-use vs. alternatives.

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