Search audience segments

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond annotations: matching is on the English segment name (not localized or ID-based) and it queries Google's external catalog. It says nothing about rate limits or result ordering, so it is solid but not rich.

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 core action and return value, then supported by the useful in-market/affinity definitions and examples before the API link. Every sentence earns its place; it is efficiently sized for a four-parameter search tool.

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 structure need not be described. Given the low complexity, annotations, and full schema coverage, the description supplies the conceptual context (what the two segment types mean, how matching works) an agent needs. It is nearly complete, though a note on how results relate to attachment siblings would close the workflow loop.

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 (query, kind, limit, customer_id) are already documented in the schema; baseline is 3. The description adds minor value by giving example query terms ('running', 'insurance', 'travel') and noting English matching, but adds no syntax or format detail beyond the schema.

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 verb (find) and resource (Google's in-market and affinity segments) and clarifies the payload value: returning the segment_id to attach. It further defines the two segment kinds, so the agent knows exactly what is being looked up. It does not explicitly differentiate itself from similar siblings such as get_audience_lists or draft_audience_attachment, so it stops short of a 5.

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?

The phrase 'with the segment_id to attach' implies this is a discovery step feeding an attachment workflow, which is light usage guidance. However, there is no explicit when-to-use, when-not, or named alternative versus get_audience_lists or search_reddit_targeting. Usage is only implied.

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