List ad groups

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral value by disclosing the default archival filter and hinting at returned fields (readable max bid, context hints, serving issues). It says nothing about pagination, result limits, or error behavior, which is a notable gap given there is no output 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?

Two short sentences with no filler, and the archival-default caveat is placed last where it reads as a modifier on the listing scope. The first sentence is grammatically compressed ("with bidding..., context hints and serving issues"), which is terse but still parseable.

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 two-parameter read-only list tool with no output schema, the definition covers scope, default filtering, and enough field hints for the agent to know what comes back. The remaining gap is pagination/result-size behavior, which is common for list endpoints and unaddressed here.

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 only 50% — campaign_id is documented, include_archived is not — so the description must compensate, and it does: "Archived ad groups are hidden unless asked" explains exactly what include_archived toggles and its default. It adds no format detail beyond the schema's existing campaign_id pattern, but the include_archived semantics are the meaningful gap and it is filled.

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?

Names a specific resource and scope ("Ad groups of a campaign") and enumerates what each record carries (bidding with readable max bid, context hints, serving issues), which distinguishes it from get_ad_group and list_ads. The phrasing is a noun fragment rather than a verb phrase, so the action ('list') only comes from the title, but the meaning is unambiguous.

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?

Usage is implied: this is the tool for enumerating the ad groups of one campaign. The only explicit conditional is "Archived ad groups are hidden unless asked," which tells the agent how to trigger include_archived. No comparison to get_ad_group or list_ads is offered, so the agent must infer it should use this rather than the single-object getter.

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