conduyt_whatsapp_connect

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

With no annotations, the description carries the full load and does so well: it discloses server-side Twilio verification, the exact failure modes and codes (422 sender_not_found / sender_not_online, 409 sender_in_use, 422 twilio_required), the one-sender-per-account constraint, and the required settings:edit permission. It also warns of the real side effect of disconnect — workflow steps on the WhatsApp channel stop sending.

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-loaded with the action and resource, then prerequisites, then the disconnect alternative. Dense and information-rich with no filler, though the packed parenthetical error-code list makes the single paragraph harder to scan than bullet-style structure would.

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?

Covers prerequisites, mutation semantics, failure codes, and the destructive disconnect path — enough to call it correctly without an output schema. It stops short of saying what a successful connect returns or how to verify the result afterward (presumably conduyt_whatsapp_status).

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 baseline is 3, but the description adds genuine meaning: the SID must belong to this account and be ONLINE, must be obtained from conduyt_whatsapp_senders, and disconnect flips to a DELETE that breaks existing workflow steps. Only the SID format itself is left to the schema.

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 ('Connect the account's WhatsApp sender') plus the underlying endpoint, and names the sibling that supplies the required value (conduyt_whatsapp_senders), distinguishing it from conduyt_whatsapp_status and conduyt_whatsapp_senders without opening either schema.

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?

Explicitly says where the senderSid must come from and describes the inverse operation ('Pass disconnect: true to forget the sender instead'). It gives clear triggering context and prerequisites (settings:edit) but never states when a caller should not use this tool, e.g. preferring conduyt_whatsapp_status to check current state first.

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