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

Annotations already flag destructive/openWorld/non-idempotent, and the description adds genuinely non-obvious behavior: credit use and changes require user approval with confirmed=true, writes are never auto-retried, saving without an audience incurs no charge, and design generation is instant with no polling. These are exactly the operational risks an agent needs before invoking a paid, destructive write.

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?

Purpose is front-loaded and the sentences are dense with distinct rules rather than filler. It is a single long block that repeats some schema-documented behavior (launch defaults, accepts_properties defaults), and the redundant opening sentence could be dropped.

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 complex, credit-consuming mutation with a nested body and no output schema, the description covers audience rules, draft-vs-ready-vs-launch states, post-creation property additions, approval gating, and retry semantics. It does not say what the response returns (e.g., the new campaign id), which an agent would need to chain follow-up calls.

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 moderate and the nested properties already carry descriptions, but the description adds constraints not present in the schema: the name must not start with 'Draft - ' and every step needs a design when saving as ready. It also restates the audience mutual-exclusivity and accepts_properties rules, which are already in the schema, so it is additive but partly redundant.

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 second sentence states a clear verb+resource ('Create a new mail campaign'), which unambiguously separates it from the read/patch siblings (get_mail_campaigns, patch_mail_campaigns_id). The opening 'Create campaign.' merely restates the title and adds nothing, but the rest is specific about what is being created and how steps/audiences work.

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?

It gives explicit branching: with an audience, either launch=true now or leave as draft and call POST /campaigns/{id}/send later; without an audience, it is saved as ready and accepts properties. It also states the accepts_properties=true condition for adding properties after start. The only gap is that it names HTTP endpoints rather than the sibling tool names (dealmachine_mail_campaign_send, dealmachine_mail_campaign_add_properties).

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