This WhatsApp automation server has 20 tools with consistent naming conventions and mostly complete input schemas defined via Zod. However, critical gaps exist: (1) NO output schemas documented for any tool, LLMs cannot plan downstream operations or extract chained IDs; (2) tool descriptions are extremely minimal (avg ~15-30 chars), providing almost no context for when/why to use each tool; (3) parameters lack actionable guidance on formats, constraints, and error recovery; (4) no visible error handling or recovery guidance; (5) several tools (e.g., connect_instance, restart_instance) omit the instanceName parameter they obviously require, indicating schema incompleteness. Naming follows verb_noun convention well (send_text, create_instance, delete_instance), but descriptions fail to explain unique purpose, prerequisites, or return structure. This is a borderline C/D server: schemas exist but are underspecified, descriptions are stubs, and critical LLM-facing guidance is absent.
No output schemas documented for any of the 20 tools. LLMs cannot infer what fields are returned, preventing proper chaining and downstream tool calls. This is a critical blocker for agent reasoning.
Tool descriptions are trivial stubs (15-40 chars), providing minimal guidance for LLM selection. Example: 'Get the connection state of a WhatsApp instance' (48 chars) lacks context on when to call it, what it returns, or how to use the result. Descriptions should be 50-200 chars explaining WHAT, WHEN, and WHY.
fetch_instancesconnect_instance
Recommendations
Document the output schema for every tool. Include example responses showing field names, types, and meaning. E.g., 'send_text returns {message_id: string, timestamp: ISO8601, status: "queued"|"sent"|"failed"}'. This is non-negotiable for LLM chaining.
Expand every tool description to 80-150 chars. Use the template: '[ACTION] the [RESOURCE]. [WHEN]: Use this when [context]. [RETURNS]: You will get [what]. [EXAMPLE]: e.g., to send a message to John, call send_text(number="5511999998888", text="Hello").' Do not include example values in the description itself, but frame when the tool should be called.
For tools with empty/incomplete schemas (connect_instance, restart_instance, etc.), add instanceName as an explicit required parameter with description 'The name of the WhatsApp instance to [action].' Do not hide required parameters in comments.
Add a clear error handling section to each tool's description or create a separate error_handling tool that explains: (1) 'Invalid phone number format: must be E.164 (country code + 10-15 digits) or JID (number@s.whatsapp.net). E.g., 5511999998888 or 5511999998888@s.whatsapp.net.' (2) 'Instance not found: check the instance name with fetch_instances().' (3) 'Connection failed: call connect_instance() and scan the QR code before sending messages.'
Add format constraints and ranges to parameters. E.g., 'delay: number in milliseconds, 0 - 60000 (max 1 minute). Example: 5000 for 5 seconds.' Use regex patterns in schemas where applicable.
Implement a confirmation pattern for delete_instance: add an optional 'confirm' boolean parameter (default false). If false, return a warning message and ask the user to call again with confirm=true. Prevent accidental deletions.
Score history
Overall score trend
↑ 49 points across a rubric change (v1 → v2)
49/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
49
2026-07-28+
v2
2026-03-09
F
0
-
v1
restart_instancewriteauthsource verified47/100
Restart a WhatsApp instance
send_contactwriteauthsource verified66/100
Send a contact message via WhatsApp
send_listwriteauthsource verified60/100
Send a list message via WhatsApp
send_locationwriteauthsource verified67/100
Send a location message via WhatsApp
send_mediawriteauthsource verified68/100
Send a media message (image, video, or document) via WhatsApp
send_pollwriteauthsource verified64/100
Send a poll message via WhatsApp
send_ptvwriteauthsource verified56/100
Send a Push To Video (video note) message via WhatsApp
Several tools (connect_instance, restart_instance, get_connection_state, logout_instance, delete_instance, find_settings) have empty or nearly empty input schemas. The code comments say 'instanceName is part of the URL, handled globally', but this is not visible in the Zod schemas provided, making it unclear how the LLM should pass the required instanceName. This suggests incomplete schema registration or missing context parameter.
No error handling documentation. Tools lack guidance on retryable vs fatal errors, validation failures, or recovery steps. E.g., if send_text fails due to invalid phone number, there is no message explaining the constraint or suggesting next steps.
No documented constraints on phone number format (send_* tools accept 'number' but do not describe required format: country code prefix, JID vs E.164, length limits). LLMs will guess and pass invalid formats.
Destructive operations (delete_instance) lack confirmation or dry-run support. An LLM can permanently delete an instance without a chance to verify intent.
Parameter descriptions for complex nested objects (e.g., send_text 'options' with 'quoted' containing 'key' containing 'id') are overly nested and hard for LLMs to navigate. No examples of valid message ID formats or quoted message structure.
No pagination documented for fetch_instances or list-like responses. If a user has 1000 instances, the response could overwhelm context or timeout.
fetch_instances
For send_* tools, document the exact recipient format: 'number: string, format is either (1) phone number with country code, e.g., 5511999998888, or (2) WhatsApp group JID, e.g., 120363024529967222-1234567890@g.us. Call fetch_instances() to see available groups.'
Add pagination to fetch_instances: accept optional 'limit' (1-100, default 20) and 'offset' (default 0) parameters. Return {instances: [...], total: number, offset: number} so LLM can iterate through large lists.
Clarify the relationship between set_presence and get_connection_state. Document: 'set_presence changes the user's online/offline status in WhatsApp. Call get_connection_state first to verify the instance is connected; set_presence will fail if the instance is not connected.'
For send_contact, document the wuid format (WhatsApp User ID). Example: 'wuid must be phone number with country code, e.g., 5511999998888. This is the same format as the "number" parameter in send_text.'
Create an examples document or expand descriptions with one concrete example per tool. E.g., 'send_text(number="5511999998888", text="Hello World", options={delay: 2000})' shows how nested options work.