openai ads search locations

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructive:false, so the safety profile is covered. 'Native fields and pagination are preserved' is the only added behavioral claim and is too vague to act on – it hints at raw-API passthrough and paging without saying what paging looks like or how large result sets are handled.

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?

Three short sentences with the search action front-loaded and no padding. The write-schema cross-reference is the one sentence that does not clearly earn its place on a read-only location search.

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?

With an output schema and full annotation coverage, little else is required; the description names the resource and the filtering domain. The odd reference to get_write_schema slightly muddies rather than completes the picture, and query-matching semantics remain unstated.

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%, and the adAccountId entry already explains the adacct_ scoping and refusal behavior. The description adds nothing about the nested query object — how `q` matches (prefix vs substring, case sensitivity) or what `limit` defaults to — so it sits at the baseline.

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 (search) plus a precise resource (country, region and market location IDs) and the reason for it (campaign geographic targeting). That is enough to separate it from every get_*-style sibling, though it never explicitly says 'use this instead of X'.

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 'for campaign geographic targeting' clause implies when the tool applies, but there is no explicit when-not, no prerequisites, and no named alternative. The closing pointer to openai_ads_get_write_schema is a cross-reference, not usage routing, and is puzzling on a read-only lookup tool.

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