Send WhatsApp text message

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it discloses the unofficial WhatsApp Web/QR channel, the ban/restriction risk, that a sent message cannot be reliably un-sent, and that retrying after a timeout without checking chat history is dangerous. That is exactly the context annotations cannot carry.

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 and use cases are front-loaded, and every sentence carries weight — the safety block is long but justified for a destructive, non-idempotent send with real ban consequences. It could be tightened slightly (the opt-in line and the ban-risk line overlap), but nothing is filler.

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?

Return behavior is stated ("Returns the message id and status") even though no output schema exists, and the mutation risks, opt-in requirement, and retry policy are all covered. For a 5-param destructive send tool, an agent has everything needed to call it safely.

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 description coverage is 100%, so number, text, reply_id, digitando, and instance_id are all already documented with formats and defaults. The description only restates reply_id ("Supports replying to a message via reply_id") and alludes to instance selection, adding no format or edge-case detail beyond the schema. Baseline 3 applies.

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?

Opens with a specific verb and resource ("Sends a plain text message to one WhatsApp number or group") and scopes it to the chosen instance, which cleanly separates it from siblings like send_media, send_buttons, send_poll, and send_location. An agent can pick this over those alternatives without opening any 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 names the use cases ("replies, notifications and one-to-one conversations") and the exclusion of bulk/unrequested messaging, plus an operational guardrail ("confirm text and recipient with the user first if there is any doubt") and a retry rule after timeouts. This is when-to-use, when-not-to-use, and prerequisite guidance in one place.

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