Draft Reddit campaign changes

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

Annotations only provide readOnlyHint=false and destructiveHint=false, which tell the agent almost nothing about side effects. The description fills this gap by stating that this is a draft operation ('Draft changes'), that 'the preview shows old → new per field', and that hours apply in each viewer's local time rather than the account time zone. It also discloses that budgets are checked against max_daily_budget practice. This is meaningful behavioral context beyond the annotations.

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?

The description is longer than average but well structured: a one-line summary of scope, followed by conditional constraints alerts, then budget validation, preview behavior, and a dedicated schedule explanation. Every paragraph adds needed information, and the schedule details are essential given the schema's vague anyOf array of objects. It could be slightly tighter, but nothing is wasted.

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 tool with an output schema, the description covers the ambiguous fields and the primary routing decision. It mentions the draft semantics and preview, which is critical for setting expectations. The only slight gap is not explicitly stating that the draft must later be applied via confirm_and_apply, but the sibling tool's name makes this obvious in context. Overall, the description equips an agent for correct invocation.

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 0%, so the description carries the full burden of parameter meaning. It covers the core fields (name, run dates, spend cap, daily/lifetime budget, bid types, schedule) and gives a highly detailed specification for schedule: valid day names, hour range 0-23, end_hour inclusive, the native object form, and [] to clear. This is far more than the schema provides and allows an agent to construct correct schedule payloads.

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?

The description opens with 'Draft changes to a Reddit campaign' — a specific verb and resource — and enumerates the exact editable aspects: name, run dates, spend cap, and (CBO only) budget/bid/schedule. It also distinguishes itself from the sibling update_reddit_ad_group by stating when that tool should be used instead. This is purpose clarity at the level expected of a well-designed definition.

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 states the condition 'CBO only' for budget/bid/schedule and provides a direct alternative: 'otherwise the budget lives on its ad groups (use update_reddit_ad_group).' It also clarifies budget validation against max_daily_budget, which informs whether the tool will accept a given input. These are concrete when/why instructions that leave little to inference.

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