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 behavioral burden. The verb 'Query' conveys read-only intent, which is the key safety-relevant trait. However, it does not disclose provider-specific differences between GSC and Bing APIs, rate limits, or the aggregated/grouped nature of the result rows. Adequate but thin given zero annotation coverage.

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?

A single 23-word sentence that is front-loaded with the action and resource, names the returned metrics, and identifies both providers. There is no filler, and every phrase earns its place.

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?

The tool is moderately complex — 13 parameters, two providers, no output schema, no annotations. The schema fully documents parameters and the description names the return metrics, but the description omits provider-specific caveats, result aggregation semantics, and usage boundaries. Sufficient for basic invocation with the three required parameters, but incomplete for nuanced calls.

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% with every parameter already documented (enums, defaults, date formats, filter syntax), so the baseline is 3. The description adds marginal value by naming the computed metrics, which conceptually maps to what the tool returns, but it contributes nothing about parameter syntax or constraints beyond the schema.

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 uses a specific verb ('Query'), a specific resource ('search performance and analytics data'), enumerates the returned metrics (clicks, impressions, CTR, average position), and names both supported providers (Google Search Console, Bing Webmaster Tools). It is immediately distinguishable from siblings like inspect_url (URL-level data) or list_sitemaps (sitemap management) without needing to inspect the schema.

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 use case is implied by the resource it queries — aggregate search performance metrics across two engines — and the sibling names make the contrast obvious. However, the description never explicitly states when to use this tool over an alternative, nor does it mention exclusions or prerequisites, leaving the agent to infer routing from sibling names alone.

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