Send / schedule a template broadcast from an Excel/CSV

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

No annotations are provided, so the description carries the full behavioral burden — and it delivers. It discloses that scheduled sends are saved as a campaign, that every original column is stored per-recipient as rowData for later automations, that the org's opt-out flow auto-excludes recipients, that the response echoes optOut/consent, and that numbers without a saved org country must be full E.164 or the send is rejected. This is rich, honest behavioral disclosure for a mutation tool.

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 a dense block but every sentence earns its place given 17 parameters and no annotations. It front-loads the core purpose before diving into parameter mechanics, scheduling, and compliance. It is efficient rather than padded, though it could be broken into cleaner sub-sections for readability. No waste, just length justified by complexity.

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 tool with 17 params, nested objects, no output schema, and no annotations, this is about as complete as it gets. It covers core usage, both variable-mapping strategies, scheduling semantics, rowData persistence, compliance/opt-out, consent, and the defaultCountry rejection rule. It even previews response fields (optOut, consent) despite the lack of an output schema. Nothing an agent needs to call it correctly 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?

Despite 88% schema coverage, the description adds substantial meaning: it explains the rows structure (one object per row keyed by column header), the ordered vs named distinction between variableColumns (1st column → {{1}}) and variableMapping, the semantics of scheduling fields, and the defaultCountry internationalization caveat. It clarifies relationships the schema leaves implicit (variableColumns vs variableMapping as alternatives, scheduling fields forcing campaign save).

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 leads with a specific verb+resource: 'Broadcast a WhatsApp TEMPLATE to everyone in an Excel/CSV' and frames it as a 'mail-merge blast', which instantly distinguishes it from the single-recipient siblings gambot_send_template and gambot_send_text. The title also adds the scheduling dimension ('Send / schedule'). Purpose is unambiguous and well-differentiated from a large sibling list.

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 instructs the agent to read the sheet and pass specific fields, gives a concrete TIP to call gambot_get_template_variables first to learn the expected variable count, and clearly separates immediate sends from scheduled ones ('Sends immediately by default; to SCHEDULE add...'). The 'easiest way to do a mail-merge blast' framing implies the alternative is the single-recipient send tools. Both when and how are covered.

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