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

Annotations already cover read-only/open-world/non-destructive status, but the description adds material context beyond them: the per-site Google Ads connection requirement, the absence of a platform-account fallback and the reasoning for it, and the concrete failure mode (returns configured:false with an explanation). It also tells the agent what to do and how to label results when that failure occurs, which is exactly the behavioral detail annotations cannot convey.

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?

It is a single dense paragraph, but it is front-loaded with the core purpose and each subsequent sentence carries distinct payload (sibling differentiation, prerequisite, failure mode, fallback). The one slightly redundant element is the repeated framing of 'this is YOUR seed keywords,' but overall the length is justified by the number of behaviors it must convey.

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?

There is no output schema, so the description carries the burden of explaining return behavior — and it does, specifying the configured:false shape and the recovery path. Combined with the prerequisite and sibling routing, an agent has everything needed to decide whether to call it and how to interpret the result.

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%, so all four parameters (seeds, site_id, location_code, limit) are already documented in the schema, and the baseline is 3. The description reinforces that seeds are the agent's own seed keywords and that targeting is location-specific, but adds no format syntax or constraints beyond what the schema already states.

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 names a specific verb+resource combination (LIVE Google Ads Keyword Planner search from seed terms) plus a scope qualifier (targeted at a specific location) and immediately states what the output can be used for (real volume, competition, CPC to cite in reports, not estimates). It explicitly distinguishes itself from the sibling get_competitor_keyword_overlap by contrasting seed-keyword research against competitor-domain lookup, so an agent can route between them without opening schemas.

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?

States exactly when to use it (your own seed terms), when not to (competitor domain — use get_competitor_keyword_overlap instead), and the hard prerequisite (the site must have its own connected Google Ads account via connect_google_ads, with no platform-account fallback). It also prescribes the fallback workflow when the prerequisite is unmet, naming check_tracked_keyword_rankings for verifying candidates. This is explicit routing in both directions.

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