get_advanced_search_analytics

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 discloses behavioral details like row_limit max 25000, start_row for pagination, data_state options ('all' vs 'final' with 2-3 day lag), and filters overriding single filter parameters. However, it does not mention rate limits, error conditions, or explicitly confirm this is a read-only operation.

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 a structured Args list preceded by a one-line summary. Every line provides essential context for a tool with 14 parameters. It is long but not verbose, with each parameter earning its place. The use of code formatting and examples improves readability.

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 (14 params, no schema descriptions, no annotations), the description is exceptionally complete. It covers all parameter semantics, usage nuances, and includes example values. An output schema exists, so return value explanations are unnecessary. The only minor gap is explicit comparison to sibling tools, but this is not essential for correct invocation.

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%, yet the description thoroughly documents every parameter: formats, defaults, valid values, and examples. For instance, it explains the exact format of site_url, the JSON structure for filters, and the meaning of data_state. This fully compensates for the missing schema descriptions.

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 'Get advanced search analytics data with sorting, filtering, and pagination.' This specifies the verb, resource, and key capabilities. It does not explicitly differentiate from the sibling 'get_search_analytics', but the 'advanced' qualifier and feature list imply a distinction.

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 concrete usage context, such as using an exact GSC property URL from list_properties, domain properties covering all subdomains, and how to analyze a specific subdomain. It also explains when to use 'filters' instead of single-filter parameters. However, it does not explicitly mention when to use this tool over 'get_search_analytics' or other alternatives.

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