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

Annotations already declare non-read-only, non-destructive, non-idempotent, open-world, so safety is covered. The description adds genuinely non-obvious behavior: image generation only applies to posts not yet written, costs one credit per post, uses the cheapest model, and the agent should confirm the cost with the user before enabling. That confirmation requirement and the scope-of-effect detail are exactly the kind of thing structured fields cannot convey.

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 sentences, front-loaded with the core action and the set of changeable settings, then the patch rule, then the cost warning. Nothing is padding, though 'say the number before turning them on' is slightly colloquial and could be phrased as an explicit confirmation instruction.

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 5-param mutation with no output schema, the description covers the essential unknowns: which settings exist, that updates are partial, and that one setting has a real credit cost requiring user confirmation. Missing only minor details such as whether changes take effect retroactively or can be reverted, which are unlikely to block a correct call.

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 80%, so the baseline is 3; the description earns above that by adding cost semantics and the forward-looking scope of withImages ('posts not yet written', 'a credit each') and by restating the patch contract ('pass only what changes'). Name and leadDays remain bare in both schema and description, which keeps it from a 5.

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 a specific verb and resource ('Changes how a campaign runs') and then enumerates the four settings that can change: images, calendar slots, lead days, name. That clearly distinguishes it from pause_campaign/start_campaign/delete_campaign. It stops short of explicitly contrasting it with edit_campaign_plan, which also touches campaign behavior, so sibling differentiation is partial rather than complete.

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?

'Pass only what changes' usefully establishes partial-update semantics, which is the main usage question for a 5-param patch tool. But there is no guidance on when to use this versus edit_campaign_plan or write_campaign_posts, and no stated prerequisites (e.g. campaign must exist or be in a certain state). Usage context is implied rather than spelled out.

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