List search appearances

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description adds value by disclosing the two-step workflow: this call enumerates named appearances and a second tool decomposes them. It also notes that returned names are what the follow-up consumes. It does not mention pagination, row limits, or quota behavior.

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?

Two short sentences, zero filler, with the enumeration purpose front-loaded and the required next step immediately after. Nothing could be cut without losing routing information.

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?

For a read-only listing tool with an output schema that documents returns and annotations that cover safety, the description supplies the missing workflow context. The only gap is search_type, the one parameter with no schema description and no mention here, which leaves an ambiguity for non-default search types.

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 80% with well-documented date, site_url, and data_state parameters, so the schema carries the semantics. The description adds no parameter detail whatsoever — nothing about search_type choices, date defaults, or property formats. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb and resource ('list the search appearances ... the property had') and immediately defines the term with concrete examples (rich results, VIDEO, REVIEW_SNIPPET), plus what it returns (clicks and impressions). It also distinguishes itself from the query_* analytics siblings by scoping to result features rather than overall search performance.

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?

Explicitly frames itself as 'step one' and names the follow-up tool and how to invoke it ('call query_search_appearance with one of the names'). However, it gives no guidance on when to prefer the other analytics siblings (query_search_analytics, query_image_analytics, etc.) for aggregate performance data, leaving that exclusion to inference.

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