OpenAI Ads campaigns

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered; the description adds value beyond that with pagination behavior ('Reads up to `limit` rows (next_after while has_more)') and data-shape caveats (budgets in micros of account currency, times in unix seconds, names are third-party text). It does not mention rate limits or auth/permission requirements, so it stops short of 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 verb and resource, then the returned fields, then pagination and the sibling hand-off. The field enumeration is a dense run-on sentence, but every clause carries information an agent can use; nothing is padding.

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?

There is no output schema, so the description carries the return-shape burden and does so fully: it lists the exposed fields and their units/formats, documents the pagination contract and the id hand-off to sibling tools. Nothing essential for correct invocation 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%, so the baseline is 3, but the description adds a meaningful tie-back the schema does not state: it links `limit` and `after` into a concrete pagination loop ('next_after while has_more') and explains that the budget value's unit is micros of the account currency. That is real semantic enrichment rather than restatement.

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 OpenAI Ads (ChatGPT ads) campaigns'), names the underlying endpoint, and enumerates the returned fields (id, name, status, bidding_type, budget in micros, start/end time, mode, timestamps). It is clearly distinguishable from sibling readers like openai_ads_ad_groups or openai_ads_insights.

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?

Explicitly routes the agent downstream: 'Use the ids with openai_ads_ad_groups, openai_ads_insights or openai_ads_plan_pause.' That gives clear when-to-use context for the returned ids and names the adjacent readers, though it never states when to prefer this listing over openai_ads_account or when not to call it (e.g., no client configured).

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