gsc_cannibalization

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It does not explicitly state that this is a read-only operation, nor does it describe the return format, filtering behavior, or any side effects. It mentions the concept of cannibalization but fails to disclose operational details like whether site_url is required or how dates are interpreted.

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 concise, with a clear front-loaded purpose and a brief Args section. It avoids verbosity and communicates the core idea efficiently. The structure is easy to scan, though the Args section is sparse and could benefit from covering more parameters without bloat.

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 (7 parameters, no annotations, 0% schema coverage, and an output schema that is not described), the description is incomplete. It fails to explain the purpose of several parameters, does not mention any required inputs or defaults beyond the schema, and gives no indication of the output structure. An agent would struggle to call this correctly without additional information.

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%, so the description must compensate. It documents only two of seven parameters (min_pages and min_impressions) with some context ('how many competing URLs before it counts'), but it omits critical parameters like days, limit, end_date, site_url, and start_date. The default values are already in the schema, so the description adds minimal value beyond two parameters.

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 states the tool's purpose as 'Queries where several of your own URLs compete for the same term,' which is a specific verb-resource combination. It clearly identifies the concept of keyword cannibalization and implies a read-only search. However, it does not explicitly differentiate from siblings like gsc_top_queries or gsc_content_decay, relying on the reader to infer the unique angle.

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?

No explicit guidance is given on when to use this tool versus alternatives. The description explains what the tool does but does not mention any prerequisites (e.g., requiring site_url), nor does it contrast with sibling tools like gsc_search_analytics or gsc_top_pages. The intended use case is implied but not stated.

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