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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds the crucial two-phase confirmation flow (first call returns a confirmation card, execution requires confirmation_token), the persistence semantics ('applies the exact stored workflow_messages through the campaign service'), and a clear non-behavior boundary ('never launches or sends'). This goes well beyond what annotations 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?

Front-loads the core purpose and the preferred selector pattern, then moves into the confirmation mechanics. It's a long description but most sentences carry distinct information; a touch of tightening (e.g., repeating the campaign_name/app_name purpose) would help.

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, two-phase mutation on nested workflow_messages with no output schema, the description covers what's modified, what the first call returns, what the second call does, what is never done (no launch/send), and how to select items. Nothing material for correct invocation is missing.

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 100%, so the baseline is 3, but the description adds genuinely useful semantic distinctions: message_order vs step_order fallback behavior, allowed personalization variables, the exactly-one-selector constraint, and the preview role of campaign_name/app_name. That said, several of these are also echoed in schema descriptions, keeping it just above baseline.

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?

States a specific verb and resource: updating message content on existing steps in a draft or paused campaign. It clearly distinguishes itself from siblings like update_campaign_settings (settings, not workflow messages) and create_campaign_draft. The scope constraint ('existing steps', 'draft or paused') further narrows it.

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 explicit selection guidance: prefer one-based message_order that skips invite/follow steps, use step_order only when exact raw order is known, provide exactly one selector plus a template per item. This is precisely the kind of when-to-use-A-vs-B guidance that prevents invocation errors.

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