google_ads_auction_insights_analyze

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

No annotations are provided, so the description carries the full burden. It explicitly states 'Read-only' and explains that competitor-level data is no longer available via the API, only impression-share proxies. It details the insight fire conditions. While comprehensive, it does not mention rate limits or specific permissions required, though the read-only nature suggests safety. A score of 4 reflects good transparency with minor gaps.

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 relatively lengthy but well-structured and front-loaded with the tool's purpose. Each sentence adds value, including the return structure, insight thresholds, API limitation context, and sibling reference. While dense, it is concise for the complexity of the tool. A score of 4 reflects very good structure and efficiency.

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?

Despite no output schema, the description explicitly lists the return structure and notes that impression-share values can be None. It explains the conditions under which insights fire and references the API limitation and sibling tool. All three parameters are documented in the schema, and the description adds meaningful context about the metrics and usage. The tool is well-documented for its complexity.

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 coverage is 100% with clear parameter descriptions. The description adds some usage guidance for the 'period' parameter (e.g., shorter windows for recent changes) but does not further elaborate on other parameters. Since the schema already provides sufficient semantics, the description adds marginal value beyond guidance, resulting in a baseline 3.

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 interprets impression-share metrics and surfaces human-readable insights. It distinguishes from sibling google_ads_auction_insights_get which returns raw metrics without insights. The verb 'Interpret' and resource 'campaign impression-share metrics' are specific, and the differentiation from alternatives 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 explicitly states when to use this tool versus the sibling: 'For the raw metrics without insights use google_ads_auction_insights_get; full competitor data is only available in the Google Ads UI.' It also provides guidance on period selection: 'Use a shorter window (LAST_7_DAYS / LAST_14_DAYS) when diagnosing recent changes; use LAST_90_DAYS for trend baselines.' This offers clear context and alternatives.

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