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

Goes well beyond the annotations: it discloses that this is a staged/draft operation returning a plan_id preview with old → new per field, that nothing commits until confirm_and_apply, that budgets are in account currency and validated against max_daily_budget, and that bid_value is checked against max_bid_increase_pct. It also warns that a campaign schedule replaces every ad group's schedule. This reconciles nicely with readOnlyHint=false / destructiveHint=false by clarifying the two-step draft-then-apply flow.

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 one-line summary followed by two tight paragraphs covering conditionality, validation, and the confirm flow. Every sentence carries signal, with only the API docs link being mild filler.

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 12-parameter mutation tool with an output schema, the description supplies the CBO conditionality, currency/unit semantics, validation limits, and the draft-to-apply lifecycle. Combined with the existing output schema and annotations, an agent has everything needed to invoke it correctly.

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 coverage is already 100%, so the baseline is 3, but the description adds real meaning on top: it flags which parameters are CBO-only, the account-currency unit, and the validation limits each value is checked against. It does not restate every field, which is appropriate given the detailed 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?

Opens with a specific verb+resource ('Draft changes to a Reddit campaign') and enumerates the mutable field families (name, run dates, spend cap, CBO budget/bid/schedule). It also positions itself against the sibling update_reddit_ad_group by noting where budget lives when CBO is not used, so an agent can distinguish it 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?

Clearly states the condition that gates the CBO-only fields and redirects non-CBO budget edits to update_reddit_ad_group, plus that confirm_and_apply is the step that actually commits. It lacks an explicit contrast against the similarly named draft_reddit_campaign sibling, so routing isn't fully unambiguous, but the usage context is strong.

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