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

Annotations already flag destructive=true and idempotent=false, yet the description adds substantial context beyond them: OpenAI rejects lowering below recorded spend, windows cannot overlap, completed windows are immutable, the required revision is auto-read, and the dry run reports the account-wide delivery effect. It also discloses the auth requirement (admin key with billing permission) and the tool's own failure message.

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?

Information-dense and front-loaded, with the action enum second so the operational mode is established early. It is long and uses backtick-heavy inline notation, but nearly every clause adds a real constraint rather than restating the name.

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?

For a destructive, 10-parameter mutation tool this is thorough: auth, dry-run behavior, immutability rules, date semantics, and delivery consequences are all present, and an output schema exists so return values need no explanation.

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?

With 0% schema coverage across 10 parameters, the description carries the full burden and does well for the important ones: the action enum, end_date exclusivity with a concrete example, amount as total vs. per-day, no_end_date and its start_date default, and confirm. It leaves name, io_id, account, and window_id unexplained, so it falls short of complete coverage.

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?

Opens with a specific multi-verb statement of the resource and its two modes (date-range window vs. recurring daily limit), immediately distinguishing it from the read-only chatgpt_ads_spend_limits sibling. An agent can tell what the tool mutates without opening any schema.

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?

Gives rich invocation context: enumerated actions, when a window may not change (overlap, active start date, completed windows), the set_daily constraint that a new limit starts tomorrow, and confirm=false for a dry run. It does not explicitly route the agent to chatgpt_ads_spend_limits for reading existing limits, which is the only missing piece.

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