Audience lists

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the bar is lower. The description adds genuine behavioral value by describing what each record carries (type, OPEN/CLOSED status, size scope, eligibility, membership duration) and the Insights flagging behavior for sub-1,000-user and closed lists. It omits pagination/result-size behavior, so not a 5.

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 resource definition, then details on returned fields, then routing. Dense but every clause earns its place. The trailing Google Ads API doc link is boilerplate rather than tool guidance.

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?

An output schema exists, so return-value explanation is not required, yet the description still caps what to expect from returned lists. Combined with explicit sibling routing, an agent has enough to select and invoke it. Only minor gaps (pagination, result limits) remain.

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 100% for the single customer_id parameter, and the schema already documents the digits/dashes format and default-account fallback. The description implies default-account behavior via 'The account's own audiences' but adds no syntax or format detail, so baseline 3 applies.

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?

States a specific resource (the account's own audiences: remarketing/customer lists, custom segments, combined segments) and even enumerates the subtypes returned. It explicitly distinguishes itself from the sibling search_audience_segments by scoping to 'the account's own' versus Google's in-market/affinity segments.

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?

Routes the agent explicitly: use the returned ids with draft_audience_attachment, and defer Google's in-market/affinity segments to search_audience_segments. This gives both the downstream-use case and the sibling-alternative condition, leaving little inference.

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