openai ads get conversion settings

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds a useful pagination note ('Native fields and pagination are preserved'), but that is the only behavioral detail beyond structured data.

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, front-loaded with the core action. The trailing write-schema reference is arguably wasted space on a read tool, but nothing else is padded.

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?

A read-only listing tool with an output schema, full schema coverage and complete annotations does not need much more. The description covers purpose and pagination behavior; only sibling disambiguation is missing.

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%, including the adAccountId scoping rule and the native query object, so the baseline is 3. The description's pagination remark loosely maps to after/before/limit/order but adds no syntax or constraint 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 and resource: 'List the account's conversion event settings, the goals a campaign can use.' The resource is identified precisely enough to invoke, but it does not differentiate from closely named siblings such as openai_ads_get_conversion_events or openai_ads_get_conversion_pixels.

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 by the resource name rather than stated. The only explicit routing is 'See openai_ads_get_write_schema for nested request fields,' which is a curious pointer for a read-only list tool and gives no guidance on when to prefer conversion settings over conversion events or pixels.

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