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

With no annotations, the description carries the full burden and does so unusually well: it discloses that Google rows use date_range while Bing uses a rolling window, that clicks are deliberately NOT summed across engines, that total_available reflects a capped synced snapshot (a floor, not the true count), and that truncated=true means the rows are a slice. These are non-obvious behavioral caveats not derivable from 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?

Front-loaded with the purpose before the dense caveats, and the 'PAGING:' marker gives some structure. The volume is justified by the number of real caveats, though several sentences are long and tightly packed, and it reads as a single wall of text rather than cleanly segmented blocks.

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?

With no output schema and no annotations, the description supplies what those would normally carry: the shape of the per-source response (google.rows/bing.rows), the pagination fields (returned, total_available, truncated, next_offset), and the paging recipe. An agent has everything needed to call and interpret it correctly.

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 60%, so the description must compensate and largely does: it explains source defaults and the 'all' alias, couples date_range to Google rows specifically, and ties offset to the response's next_offset. The only gap is site_id, which is undocumented in both schema and description.

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 opening sentence states a specific verb+resource ('Get top keyword rankings for a site') and the rest narrows the scope by source. It is clear and unambiguous, but it never names or contrasts a sibling such as Keyword_Metrics or Bing_Keyword_Metrics, so an agent must infer tool selection from surrounding naming alone.

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?

Gives explicit when-to-use guidance across the branching parameter ('source' defaults to 'combined'; use 'google' or 'bing' for a single engine; 'all' is a back-compat alias), which is the tool's main decision point. It does not address when to choose this tool over the sibling keyword/analytics tools, so it stops short of the full alternatives coverage.

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