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

Annotations only declare the generic mutation profile (readOnly=false, idempotent=false, non-destructive, openWorld); the description adds substantial behavior beyond them: only contacts created AFTER activation qualify, each fires at most once, re-imports never trigger, one automation per tag, and the response surfaces live stats, existing_tagged_contacts, and warnings like a disconnected WhatsApp number.

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?

Dense but front-loaded: purpose leads, then trigger semantics, then the broadcast alternative, then prerequisites and return values. Nearly every sentence carries distinct information, though the paragraph is long enough that a reader must parse carefully.

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 mutation tool with strong annotations, full schema coverage and no output schema, the description covers triggering conditions, side effects, consent/prerequisite caveats, and the returned payload (automation, live stats, warnings). An agent has everything needed to call 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 100% (baseline 3), but the description adds meaning on top: delay_minutes' 0–10080 window, name's default of 'Welcome: <tag>', and the cross-reference to set_template_variables for placeholder mapping. The template approval requirement is partly restated from the schema, so not a full 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+resource+mechanism: it creates an automation that sends an approved template to every new contact gaining a tag. It is unmistakably distinct from siblings like send_broadcast (existing contacts) and update_automation/list_automations.

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 explicitly names the alternative for the adjacent use case ('To message existing contacts, use a broadcast'), lists the trigger sources (add_or_update_contact, import_contacts, REST API, Zapier/Make), and states prerequisites (approved template, mapped placeholders, consent). Nothing is left to inference.

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