Provides comprehensive tools for managing WhatsApp sessions, sending multi-format messages (text, image, file, audio, video, emoji reactions), conducting bulk campaigns, orchestrating groups (create, add/remove members, promote/demote, update subject), managing contacts (get, check, block/unblock), and configuring webhooks for real-time events.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenWA MCP Server send a message to +1234567890"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An enterprise-grade Model Context Protocol (MCP) server that seamlessly wraps the powerful OpenWA WhatsApp REST API. It exposes 44 robust tools over standard I/O (stdio) transport, enabling any MCP-compatible AI assistant (such as Cursor, Claude Desktop, Cline, and Antigravity) to securely manage WhatsApp sessions, dispatch multi-format messages, control group participants, search contacts, manage tag labels, and setup callbacks in real-time.
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā 1. AI CLIENT (Cursor, Claude, Cline, etc.) ā
ā User: "Send a promotional flyer to my active VIP groups..." ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼ [JSON-RPC over stdio]
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā 2. OPENWA MCP SERVER (TypeScript) ā
ā ā¢ Matches user request to the `send_image` tool schema ā
ā ā¢ Validates payload boundaries using declarative Zod schemas ā
ā ā¢ Authenticates securely via local dotenv environment configs ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼ [REST API Request with X-API-Key]
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā 3. OPENWA WHATSAPP REST DAEMON ā
ā ā¢ Translates API payloads into native WhatsApp Web calls ā
ā ā¢ Manages multi-session state machines & SQLite indexes ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼ [WhatsApp Network Protocol]
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā 4. TARGET WHATSAPP DEVICES ā
ā ā¢ Bulk promotional flyers delivered safely and instantly ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāRelated MCP server: WAHA MCP Server
44 Built-in Tools: Comprehensive control over the entire WhatsApp ecosystem.
Robust Zod Validation: Pure, declarative parameter validation on every request.
Zero-Poll Webhooks: Simple callbacks to receive instant WhatsApp events directly.
Multi-Session Native Engine: Manage multiple phone accounts under a single server wrapper.
Strict Separation of Concerns: Highly modular, human-written TypeScript architecture.
Node.js: v22.0.0 or higher
TypeScript: v5.0.0 or higher
A running and accessible OpenWA REST API instance
A secure API Key generated from your OpenWA server configuration
# Clone the repository
git clone https://github.com/ExoCubeYT/openwa-mcp.git
cd openwa-mcp
# Install dependencies
npm install
# Configure environment variables
cp .env.example .envEdit your local .env file to match your active OpenWA REST API backend:
OPENWA_BASE_URL=http://localhost:2785/api
OPENWA_API_KEY=your_secure_api_key_herenpm run buildThe production output will compile cleanly into the dist/index.js bundle directory.
To load the OpenWA MCP server into your favorite developer environment, reference the standard JSON-RPC launch config.
Note: Replace
C:/path/to/openwa-mcpwith the absolute local filesystem path of your cloned workspace directory.
Edit your global configuration file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"openwa": {
"command": "node",
"args": ["C:/path/to/openwa-mcp/dist/index.js"],
"env": {
"OPENWA_BASE_URL": "http://localhost:2785/api",
"OPENWA_API_KEY": "your_secure_api_key_here"
}
}
}
}Add to .cursor/mcp.json in your project root (or set globally via Settings > Features > MCP):
{
"mcpServers": {
"openwa": {
"command": "node",
"args": ["C:/path/to/openwa-mcp/dist/index.js"],
"env": {
"OPENWA_BASE_URL": "http://localhost:2785/api",
"OPENWA_API_KEY": "your_secure_api_key_here"
}
}
}
}Edit your global extension state configurations in cline_mcp_settings.json:
{
"mcpServers": {
"openwa": {
"command": "node",
"args": ["C:/path/to/openwa-mcp/dist/index.js"],
"env": {
"OPENWA_BASE_URL": "http://localhost:2785/api",
"OPENWA_API_KEY": "your_secure_api_key_here"
},
"disabled": false
}
}
}Add .mcp.json to your project workspace root:
{
"mcpServers": {
"openwa": {
"command": "node",
"args": ["C:/path/to/openwa-mcp/dist/index.js"],
"env": {
"OPENWA_BASE_URL": "http://localhost:2785/api",
"OPENWA_API_KEY": "your_secure_api_key_here"
}
}
}
}Create .vscode/mcp.json inside your local workspace:
{
"servers": {
"openwa": {
"command": "node",
"args": ["C:/path/to/openwa-mcp/dist/index.js"],
"env": {
"OPENWA_BASE_URL": "http://localhost:2785/api",
"OPENWA_API_KEY": "your_secure_api_key_here"
}
}
}
}All tool schemas are structured logically using modular TypeScript domains under src/tools/.
Tool | Params | Description |
| None | Lists all active WhatsApp web browser sessions |
|
| Launches a new browser instance for authentication |
|
| Resumes a stopped session container |
|
| Safely shuts down a running browser instance |
|
| Wipes the credentials and directory of a session |
|
| Generates a base64 pairing QR code for WhatsApp link |
|
| Returns |
Tool | Params | Description |
|
| Dispatches a plaintext message to a contact/group |
|
| Fetches and sends an image from a URL |
|
| Sends document files (PDFs, docs) from a URL |
|
| Sends audio file streams directly to a target chat |
|
| Sends high-definition videos from web URLs |
|
| Attaches a quick emoji reaction to a message |
|
| Retrieves historical context and message logs |
|
| Deletes/revokes a message for everyone |
Tool | Params | Description |
|
| Delivers text announcements to target chats |
|
| Broadcasts promotional flyers to multiple contacts |
Tool | Params | Description |
| None | Returns a list of all groups the session is in |
|
| Provisions a new group with custom contacts |
|
| Resolves admins, descriptions, and metadata |
|
| Adds a contact to an existing group |
|
| Removes/kicks a participant from the group |
|
| Grants admin permissions to a participant |
|
| Strips admin privileges from a group manager |
|
| Targeted message relay for group channels |
|
| Exits the specified group safely |
|
| Renames the group conversation title |
Tool | Params | Description |
| None | Lists all saved contacts and known numbers |
|
| Returns metadata, status, and profile information |
|
| Verifies if a raw phone number is on WhatsApp |
|
| Resolves high-resolution avatar display URLs |
|
| Instantly blocks incoming chats from a number |
|
| Restores normal chat capabilities to a number |
Tool | Params | Description |
| None | Lists active callback URLs configured for events |
|
| Subscribes a server URL to WhatsApp events |
|
| Removes an active event callback listener |
|
| Mutates subscribed events on an active webhook |
Tool | Params | Description |
| None | Fetches all custom label classifications |
|
| Creates a new colored tag label |
|
| Removes a custom label classification |
|
| Adds a label classification to a chat thread |
|
| Removes a label classification from a chat thread |
Tool | Params | Description |
|
| Downloads media files stored inside a message |
|
| Caches media on the server to prevent redelivery |
To run the codebase in live-refresh watch mode during extensions, run:
# Spawns tsx to track active source code files directly
npm run devTo run standard test transport handshakes, build the module and execute the diagnostic listener:
npm run build
node dist/index.jsWe welcome contributions of all shapes and sizes! To keep codebases pristine and secure, please adhere to our strict project design conventions.
Fork the Repository: Set up your workspace branch on GitHub.
Implement Your Logic: Maintain strict separation of concerns. Keep your tools and clients isolated.
No AI Comments: Adhere to our zero AI-style commenting standard. Use short, human-like annotations where needed, and document details in .explanation files only.
Build & Test: Ensure npm run build generates zero TypeScript errors.
Create a Pull Request: Submit your pull request for review against our development branch.
See CONTRIBUTING.md for deeper details on our design paradigms.
Distributed under the MIT License. See the LICENSE file for details.
Add a participant to a WhatsApp group
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| groupId | Yes | Group ID | |
| participantId | Yes | Phone ID of the participant to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention that adding a member typically requires admin privileges, whether notifications are sent, or error scenarios (e.g., group full, member already exists).
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 single short sentence, which is concise but lacks structure. It is not verbose, but could include key additional context in a similarly concise form (e.g., permissions, side effects).
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?
Given the tool is a mutation operation with no output schema and no annotations, the description is incomplete. It leaves out important context such as required permissions, side effects, and error handling.
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 the baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions, but the schema itself is clear enough. No further elaboration needed.
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 clearly states the verb 'Add' and the resource 'participant to a WhatsApp group', directly distinguishing it from sibling tools like 'create_group' (creates group) and 'remove_group_member' (removes member).
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?
No guidance on when to use this tool versus alternatives like 'promote_member' or 'demote_member'. No mention of prerequisites (e.g., admin status) or context for how adding a member differs from creating a group.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a label to a specific WhatsApp chat
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| labelId | Yes | Label ID to apply | |
| chatId | Yes | Chat ID to label |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose behavioral traits such as idempotency, required permissions, or side effects (e.g., if label already applied).
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?
Single, concise sentence that is front-loaded and contains no unnecessary words.
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?
Description covers the basic action, but lacks details on behavior when label already exists, effect on chat, and output expectations. Without output schema, more context would be helpful.
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% and description adds no additional meaning beyond parameter names and types. Baseline score of 3 is appropriate.
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 clearly specifies the action ('Apply a label') and the target resource ('specific WhatsApp chat'). It distinguishes from siblings like 'create_label' and 'remove_label_from_chat'.
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?
No guidance on when to use this tool versus alternatives (e.g., remove_label_from_chat). No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block a WhatsApp contact
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| contactId | Yes | Contact ID to block |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose side effects (e.g., whether blocking destroys chat history), reversibility, or authentication needs. Only says 'Block'.
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?
Single sentence with no extraneous words. Highly concise and front-loaded.
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?
Given no annotations or output schema, the description omits essential context for a destructive action. Does not cover behavior, prerequisites, or results.
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%, but parameter descriptions are minimal ('Session ID', 'Contact ID to block'). No additional meaning beyond 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?
The description 'Block a WhatsApp contact' clearly states the action and target resource. It is distinct from sibling tools like 'unblock_contact'.
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?
No guidance on when to use this tool versus alternatives (e.g., removing a contact from a group). No prerequisites mentioned, such as requiring an active session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a phone number is registered on WhatsApp
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| phone | Yes | Phone number in international format without + prefix |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond the basic check. It does not mention whether a session is required, what happens if the number is not registered, or any potential side effects. With no annotations, the description carries the full burden but is insufficient.
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 single, clear sentence with no unnecessary words. It is appropriately sized for the tool's simplicity.
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?
The description fails to clarify what the tool returns (e.g., boolean or status) or any error conditions. Given no output schema, it should provide more context about the outcome.
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?
The input schema has 100% coverage for both parameters. The description adds no extra meaning beyond what is already in the schema (sessionId and phone format). Baseline at 3 is appropriate.
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 clearly states the verb 'check' and the resource 'phone number registered on WhatsApp'. It is specific and distinguishes from sibling tools like get_contact or send_text, which have different purposes.
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?
No guidance is provided on when to use this tool versus alternatives like get_contact or get_contacts. There is no mention of prerequisites, such as requiring an active session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new WhatsApp group with specified participants
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| name | Yes | Group name | |
| participants | Yes | Array of participant phone IDs to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the creation action without disclosing authorization needs, rate limits, or side effects beyond the obvious mutation.
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?
A single, front-loaded sentence with no wasted words; every part is essential.
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?
No output schema exists, and the description omits return value or confirmation. For a creation tool, it lacks completeness.
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. The description adds no extra meaning beyond what the schema already provides for the parameters.
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 'Create a new WhatsApp group with specified participants' clearly states the verb and resource, distinguishing it from siblings like 'add_group_member' which adds to existing groups.
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?
Usage context is implied (use to create a group), but no explicit guidance on when to use vs alternatives, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new label/tag for organizing WhatsApp chats
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| name | Yes | Label name | |
| color | No | Label color hex code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Create a new label'. It does not disclose behavioral traits like uniqueness constraints, permissions, or side effects.
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 single, front-loaded sentence with no unnecessary words. It is efficient and easy to parse.
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?
The description is adequate for a simple create tool, but it omits return value information (e.g., what the tool returns upon success). Given no output schema, this gap reduces completeness.
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 the schema already documents all parameters. The description adds no additional meaning beyond listing 'name', 'color', 'sessionId'.
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 clearly states the action 'Create' and the resource 'label/tag' with context 'for organizing WhatsApp chats'. It effectively distinguishes from sibling tools like delete_label or get_labels.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., add_label_to_chat). There is no mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new WhatsApp session with the given name
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Unique name for the new session |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is very brief and does not disclose any behavioral traits beyond the basic creation action. No information about side effects, permissions, or error conditions is provided, and there are no annotations to supplement.
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 single sentence that directly states the tool's purpose. It is concise but lacks additional structure or detail that might help the agent, though it is not verbose.
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?
Given the existence of sibling tools like 'start_session' and 'delete_session', the description does not provide enough context to differentiate usage. No output schema exists, and return values are not mentioned.
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?
The input schema has 100% description coverage for the single parameter 'name', which is described as 'Unique name for the new session' in the schema. The description adds no additional meaning beyond that.
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 explicitly states 'Create a new WhatsApp session with the given name', clearly indicating the verb and resource. However, it does not differentiate from the sibling 'start_session' tool, which could cause confusion.
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?
No guidance is provided on when to use this tool over alternatives like 'start_session' or 'delete_session'. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new webhook to receive WhatsApp events at a URL
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| url | Yes | Webhook endpoint URL | |
| events | Yes | Array of event types to subscribe to | |
| secret | No | Optional webhook signing secret |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states the basic creation action, omitting side effects, validation, permissions, or whether existing webhooks are overwritten.
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?
Single sentence of 12 words, no filler, front-loaded with the core purpose. It is appropriately sized for its simplicity.
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?
Despite low complexity with no output schema or nested objects, the description does not explain what the tool returns or how to proceed after creation. It lacks information about webhook lifecycle, confirmation, or integration with sibling tools.
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?
The input schema has 100% description coverage, so each parameter is already documented. The description adds minimal value, only implying that the url is the endpoint via 'at a URL', and does not elaborate on event types or the secret parameter's purpose beyond 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?
Description clearly states the tool creates a webhook to receive WhatsApp events at a URL. It uses a specific verb and resource, and the sibling tools like delete_webhook, update_webhook, and list_webhooks are clearly distinct.
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?
No guidance on when to use this tool versus alternatives like update_webhook or list_webhooks. There is no mention of prerequisites, typical scenarios, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a label from the WhatsApp session
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| labelId | Yes | Label ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks information about behavioral traits such as irreversibility, required permissions, or side effects of deleting a label.
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 single concise sentence that is front-loaded and contains no superfluous words.
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?
Given the lack of annotations and output schema, the description is too minimal for a deletion tool. It should include details about irreversibility, permissions, or effects on related data.
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%, with both parameters described in the input schema. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
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 clearly states the verb 'delete' and the resource 'label' from 'WhatsApp session', distinguishing it from sibling tools like create_label, get_labels, and add_label_to_chat.
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?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or context for deletion (e.g., label must exist, session must be active).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a specific message from a WhatsApp chat
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| messageId | Yes | ID of the message to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action (delete) but doesn't clarify permanence, reversibility, impact on other participants, or rate limits.
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?
Single sentence with no wasted words. Front-loaded with key action and context.
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 simple 2-parameter tool, the description is adequate but lacks completeness regarding expected behavior or response after deletion. No output schema; could mention if success is indicated.
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 covers 100% of parameters with descriptions. The tool description adds no extra meaning beyond the schema, but the schema itself is sufficient.
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?
Description clearly states the action and object: 'Delete a specific message from a WhatsApp chat'. It distinguishes from sibling tools like 'react_to_message' or 'send_text' by specifying 'delete' and 'message'.
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?
No guidance on when to use this tool versus alternatives, no prerequisites or conditions mentioned. Could specify if the message must be yours or if there are permissions needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a WhatsApp session and its data
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | ID of the session to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It indicates permanent deletion and data removal, which implies destructiveness and irreversibility. However, it lacks detail on side effects or authorization needs.
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?
Single sentence, no fluff. Every word is necessary and contributes to understanding.
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?
Given the tool's simplicity (one param, no output schema), the description is nearly complete. It lacks only minor context like prerequisites or alternative tool differentiation.
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% for the single parameter sessionId, with a clear description. The tool description adds no additional meaning beyond what is in 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?
The description clearly states the action (delete), the resource (WhatsApp session), and the scope (permanently and its data). It distinguishes from sibling tools like create_session, stop_session, get_sessions.
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?
No guidance on when to use this tool vs alternatives like stop_session or any prerequisites. The description does not address whether the session should be stopped first or any other conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a webhook from a WhatsApp session
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| webhookId | Yes | Webhook ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action is a deletion but gives no information about side effects, reversibility, permissions, or error handling.
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 single sentence with no wasted words. It is concise and directly communicates the tool's purpose.
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?
Given the simple parameters and lack of output schema, the description lacks completeness. It doesn't mention expected outcomes, error states, or any behavioral nuances relevant to a deletion operation.
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?
The input schema covers 100% of parameters with descriptions, so the description adds no additional meaning beyond what the schema provides. Baseline score of 3 is appropriate.
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 clearly states the action (delete) and the resource (webhook from a WhatsApp session). It distinguishes itself from sibling tools like create_webhook, update_webhook, and list_webhooks.
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?
The description provides no guidance on when to use this tool vs alternatives, no prerequisites, and no scenarios when not to use it. It simply states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Demote a group admin back to regular participant
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| groupId | Yes | Group ID | |
| participantId | Yes | Phone ID of the admin to demote |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states the action but omits behavioral details such as permission requirements, whether the action is reversible, or what happens if the participant is not an admin.
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 single, clear sentence with no wasted words. However, it is too minimal and could be expanded with relevant usage details while remaining concise.
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?
The description is extremely terse. Given the tool has 3 required parameters and no output schema or annotations, it fails to provide adequate context about prerequisites, expected behavior, or result. It does not sufficiently guide an AI agent on invocation.
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 the input schema already documents all parameters. The description adds no additional meaning or context for the parameters beyond what the schema provides.
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 uses a specific verb 'Demote' and clearly identifies the resource 'group admin' and the outcome 'back to regular participant'. It directly distinguishes from the sibling tool 'promote_member' which performs the opposite action.
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?
The description implies usage (when an admin needs to be demoted), but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites like the user must be an admin or session must be active.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed info for a specific WhatsApp contact
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| contactId | Yes | Contact ID to look up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states 'Get detailed info' without disclosing what coverage of details, read-only nature, or any side effects. It lacks behavioral context beyond the basic action.
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?
A single, concise sentence that front-loads the core purpose. No superfluous words.
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 two required parameters and no output schema, the description omits important context: what constitutes 'detailed info', return format, prerequisites (e.g., active session), or constraints. It requires the agent to infer too much.
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% with clear descriptions for both parameters ('Session ID', 'Contact ID to look up'). The description adds no extra meaning, so baseline score of 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?
Description clearly states 'Get detailed info for a specific WhatsApp contact', using a specific verb and resource. This readily distinguishes it from sibling tools like get_contacts (listing) and check_number (verification).
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?
No guidance is given on when to use this tool versus alternatives. The description does not specify context, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all contacts stored in the WhatsApp session
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'List all contacts', which implies a read operation. However, it does not disclose any behavioral traits such as whether it returns cached data or has side effects.
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 single clear sentence with no unnecessary words. It efficiently conveys the tool's purpose.
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 simple tool with one required parameter and no output schema, the description is complete. It tells the agent what the tool does and what input is needed.
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?
The schema has 100% coverage with a description for 'sessionId', but the description adds no additional meaning beyond the schema. The format or source of the session ID is not explained.
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 clearly states 'List all contacts', specifying the verb and resource. It distinguishes itself from the sibling 'get_contact' which implies fetching a single contact.
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?
The description implicitly suggests using this tool to list all contacts, but it does not explicitly mention when not to use it or alternatives like 'get_contact' for a single contact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific WhatsApp group including members, admins, and settings
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| groupId | Yes | Group ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'get' but does not disclose side effects (likely none), error handling, or idempotency. For a read operation, it lacks confirmation that it does not modify state and does not describe what happens if the group does not exist or session is invalid.
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?
Single sentence, 15 words, front-loaded with the key action and resource. Every word is necessary and informative without redundancy.
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 read tool with 2 parameters and no output schema, the description adequately conveys the purpose and included data. However, it omits mention of session state requirements or error conditions, and it does not explain the output structure, though no output schema exists to offload that responsibility.
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?
Input schema has 100% coverage: both parameters have basic descriptions ('Session ID', 'Group ID'). The description adds context about the return value (members, admins, settings) but not about parameter semantics beyond schema. Baseline 3 is appropriate as schema already defines parameters.
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 clearly states 'Get detailed information about a specific WhatsApp group including members, admins, and settings', specifying the verb (get), resource (group info), and scope (members, admins, settings). This distinguishes it from siblings like get_groups (list all groups) or get_contact (single contact).
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?
The description implicitly indicates use for retrieving details of a specific group, contrasting with list-oriented tools like get_groups. However, it does not explicitly state when to use versus alternatives or mention prerequisites like an active session or valid group ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all WhatsApp groups visible to the given session
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states a read-like operation but does not disclose any behavioral traits such as whether it's read-only, pagination, or side effects. This is insufficient.
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 single concise sentence with no wasted words. It is front-loaded and efficiently communicates the core purpose.
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?
Without an output schema, the description should explain what the return includes (e.g., group names, IDs). It fails to provide this, leaving the agent without crucial information about the tool's output.
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% for the single parameter 'sessionId', so baseline 3 is appropriate. The description adds no additional meaning beyond the schema's 'Session ID'.
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 clearly states the verb 'List' and the resource 'WhatsApp groups', and specifies the scope 'visible to the given session'. It effectively distinguishes from sibling tools like get_group_info or create_group.
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?
The description implies usage for listing all groups for a session but does not provide explicit guidance on when to use this versus alternatives like get_group_info for specific groups, or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all labels/tags in the WhatsApp session
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Minimal disclosure beyond read-only nature; no details on pagination, ordering, or return format; no annotations to supplement.
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?
Single concise sentence front-loaded with action and resource; no unnecessary words.
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?
Adequate for a simple list tool with one required parameter; lacks return format info but no output schema exists.
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 covers 100% of parameters with description 'Session ID'; description adds no extra meaning beyond 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?
Description clearly states verb 'List' and resource 'all labels/tags in the WhatsApp session', distinguishing it from sibling tools like create_label or delete_label.
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?
No explicit when-to-use or alternatives, but the simple list operation is self-explanatory; missing context like prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download media (image, video, audio, document) from a received WhatsApp message by its message ID
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| messageId | Yes | Message ID containing the media |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Download media' without disclosing whether the download is destructive, authentication requirements, rate limits, file format/limits, or what happens if the message lacks media. For a download operation, more behavioral context is needed.
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 single, efficient sentence that conveys the core purpose without redundancy. Every word adds value.
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?
Given no output schema, no annotations, and many sibling tools, the description is too sparse. It does not explain the output format (binary, URL?), error handling, prerequisites (session must be active, message must have media), or potential side effects. More detail is needed for a download tool.
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 the schema already documents both parameters. The description adds context that the media is from a 'received WhatsApp message', but does not explain the semantics of sessionId beyond what the schema says. Baseline 3 is appropriate.
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 clearly states the verb 'Download', the resource 'media', and specifies the types (image, video, audio, document) and how to identify it (by message ID from a received WhatsApp message). This distinguishes it from sibling tools that send or manage media.
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?
The description implies the tool is for downloading media after receiving a message, but no explicit guidance on when to use it over other tools like send_* or upload_media. No exclusions or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve message history from a specific WhatsApp chat
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| chatId | Yes | Chat ID to fetch messages from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only states 'retrieve message history' without disclosing behavioral traits such as pagination, authentication requirements, rate limits, or data format (e.g., whether images are included).
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 single concise sentence that immediately conveys the tool's purpose without extraneous information. Every word earns its place.
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?
Given the simplicity of the tool (two required string params, no output schema), the description is minimally adequate but could benefit from specifying the format of returned messages or that it retrieves all messages in order.
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 the schema already documents both parameters. The description adds no extra meaning beyond what is in the schema, which is acceptable but does not compensate for any gaps.
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 clearly states the action 'retrieve', the resource 'message history', and the context 'WhatsApp chat', distinguishing it from sibling tools like send_text or delete_message.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., search_messages or get_media). The description does not mention prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the profile picture URL for a WhatsApp contact
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| contactId | Yes | Contact ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention what happens if the contact does not exist, whether authentication is needed, or the format of the returned URL. The description is too minimal for behavioral transparency.
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 single sentence that is directly to the point with no unnecessary words. It is highly concise and well-structured for quick comprehension.
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?
Given the simplicity of the tool (2 parameters, no output schema), the description is somewhat incomplete. It does not specify the return type (e.g., string URL) or behavior on missing contacts. However, for a straightforward get operation, it meets a basic baseline.
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?
The input schema has 100% description coverage, so the schema already explains the parameters (sessionId and contactId). The description adds no additional meaning beyond the schema, resulting in a baseline score of 3.
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 clearly states the action (Get) and the resource (profile picture URL for a WhatsApp contact). It distinguishes well from sibling tools, which are primarily for messaging, group management, and other operations.
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?
The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It is implied that this tool is for retrieving a profile picture, but no explicit context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the QR code data for authenticating a WhatsApp session. Use this when a session needs to be scanned with WhatsApp mobile.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | ID of the session to get QR for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'authenticating' but doesn't specify side effects or prerequisites (e.g., session must exist). However, it's a simple get operation, and the purpose is transparent enough.
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?
Two concise sentences that front-load the action and usage context. No wasted words.
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 simple tool with one parameter and no output schema, the description provides enough context: what it does and when to use it. It could mention the output format but is sufficient.
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?
The input schema has 100% coverage with a description for 'sessionId'. The description adds no extra meaning beyond the schema, meeting the baseline of 3.
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 clearly states the verb 'Get' and the resource 'QR code data for authenticating a WhatsApp session'. It distinguishes itself from sibling tools like 'create_session' or 'start_session' by focusing on QR retrieval.
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?
The description explicitly states when to use this tool: 'when a session needs to be scanned with WhatsApp mobile'. It doesn't explicitly mention when not to use or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all WhatsApp sessions currently managed by OpenWA
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates a read-only listing operation, but with no annotations, it does not disclose authorization needs, rate limits, or whether sessions are active/inactive.
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?
Single front-loaded sentence with no unnecessary words or repetition.
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?
Description is adequate for a no-parameter tool but without an output schema, it doesn't specify what fields are returned for each session, which could be ambiguous given sibling tools like get_session_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?
Input schema has no parameters (baseline 4), and description adds context by specifying that it lists all sessions, though no parameter details are needed.
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?
Description clearly states 'List all WhatsApp sessions currently managed by OpenWA', using specific verb 'List' and resource 'sessions', distinguishing it from sibling tools like create_session, delete_session, etc.
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?
No guidance on when to use this tool vs alternatives like get_session_status or get_session_qr; usage is only implied by the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the current connection status of a WhatsApp session (connected, disconnected, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | ID of the session to check |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only mentions 'check' (read operation) but omits details like whether the session must be started, error handling on invalid sessionId, rate limits, or response format. This is minimal disclosure for a status check 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 single, front-loaded sentence that efficiently communicates the tool's purpose. There is no extraneous information; every word is functional.
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?
Given the simplicity of the tool (one parameter, no nested objects), the description is mostly adequate but lacks detail about the return value (e.g., status strings like 'connected', 'disconnected'). Without an output schema, mentioning the response format would improve completeness.
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% (one parameter with clear description), so baseline is 3. The tool description does not add any additional meaning beyond what the schema provides, but it also does not detract. Rating is adequate.
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 clearly states the verb 'Check' and the resource 'connection status of a WhatsApp session', with examples of statuses. Among sibling tools like get_session_qr, get_sessions, and start_session, this tool's unique purpose is immediately evident.
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?
No guidance is provided on when to use this tool versus alternatives such as get_sessions (which may return status for all sessions) or start_session. The description simply states what the tool does without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Leave a WhatsApp group
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| groupId | Yes | Group ID to leave |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the action but does not explain consequences (e.g., losing access, potential loss of chat history, or that it cannot be undone). For a mutation operation, this is insufficient.
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?
Single sentence with no unnecessary words. Perfectly concise and front-loaded.
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?
With low complexity (2 simple params, no output schema), the description is adequate for the basic action but lacks behavioral context (e.g., what happens after leaving, any confirmation needed). Could mention that leaving is permanent without re-invitation.
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% with both parameters documented (sessionId and groupId). The description adds no additional meaning beyond what the schema provides. Baseline 3 applies since schema does the heavy lifting.
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 'Leave a WhatsApp group' clearly states the action (verb 'leave') and the resource ('WhatsApp group'). It distinguishes from sibling tools like remove_group_member (which removes others) and demote_member (which changes roles).
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?
No guidance on when to use this tool versus alternatives (e.g., remove_group_member for removing others, or deleting the group itself). No prerequisites or constraints mentioned, such as requiring membership or irreversible nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all webhooks configured for a WhatsApp session
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'List' (a read operation) but omits details like whether authentication is required, rate limits, or behavior if the session is invalid. This is insufficient for a tool with no annotations.
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 single, concise sentence with no filler. Every word is necessary and directly communicates the tool's purpose.
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?
Given the tool's simplicity (1 parameter, no output schema), the description is mostly complete. It could optionally mention the return format (list of webhook objects) or pagination, but the current version is adequate for basic comprehension.
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?
The input schema has 100% coverage (sessionId described as 'Session ID'). The description adds no additional meaning beyond the schema, meeting the baseline for high schema coverage.
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 'List all webhooks configured for a WhatsApp session' uses a specific verb ('List') and resource ('webhooks') with a clear scope ('for a WhatsApp session'). It distinguishes itself from sibling tools like create_webhook, delete_webhook, and update_webhook by focusing on listing.
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?
The description does not provide explicit when-to-use or when-not-to-use guidance. It is implied that this tool is for retrieving all webhooks, but no alternatives or exclusions are mentioned despite the presence of sibling tools like get_webhook or search_webhook.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Promote a group participant to admin role
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| groupId | Yes | Group ID | |
| participantId | Yes | Phone ID of the participant to promote |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the action ('promote') without disclosing behavioral traits such as required permissions, side effects, or reversibility. The agent is left to infer that it mutates data.
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 single short sentence (6 words) that conveys the core functionality without any redundant information. It is perfectly concise and front-loaded.
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 simple mutation tool with no output schema and minimal parameters, the description is adequate but lacks details on success/failure behavior, constraints, or related operations. It could be more complete by mentioning prerequisites or effects.
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?
The input schema already describes all three parameters with full coverage (100%). The description does not add any additional meaning beyond stating the action, so it meets the baseline but provides no extra value.
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 clearly states the tool promotes a group participant to the admin role, using a specific verb ('promote') and resource ('group participant'), and distinguishes from siblings like 'demote_member' and 'add_group_member'.
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?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context about when promotion is appropriate or forbidden.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
React to a specific WhatsApp message with an emoji
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| chatId | Yes | Chat ID containing the message | |
| messageId | Yes | ID of the message to react to | |
| reaction | Yes | Emoji reaction (e.g. š, ā¤ļø, š) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. While it describes the basic action (reacting with an emoji), it lacks details on whether the reaction is reversible, visible to others, or requires the message to exist. This is minimal but not contradictory.
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 single, concise sentence with no fluff. Every word earns its place.
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 simple action with four parameters and no output schema, the description covers the essential purpose. It could be improved by noting that the reaction must be a valid emoji, but it is generally adequate.
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%. The description's mention of emoji examples adds little beyond the schema's parameter descriptions. Baseline of 3 is appropriate.
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 clearly states the verb 'react', the resource 'specific WhatsApp message', and the means 'with an emoji'. It is distinct from sibling tools like delete_message or send_text.
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?
No explicit guidance on when to use this tool versus alternatives. The purpose is evident, but the description does not provide context for when not to use it (e.g., for system messages).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a participant from a WhatsApp group
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| groupId | Yes | Group ID | |
| participantId | Yes | Phone ID of the participant to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral transparency burden. It fails to disclose if removal is permanent, requires admin privileges, or has side effects like triggering notifications.
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?
A single sentence with no wasted words, front-loaded with the action and resource. Appropriate length.
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 simple tool with 3 required params and no output schema, the description covers the basic purpose but lacks context about prerequisites (e.g., must be admin) or consequences (e.g., cannot remove last admin). Adequate but not thorough.
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% with terse but clear descriptions. The tool description does not add additional meaning beyond the schema, so baseline of 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?
The description 'Remove a participant from a WhatsApp group' clearly states the verb (remove) and the resource (participant from a WhatsApp group), distinguishing it from siblings like add_group_member and leave_group.
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?
No guidance on when to use this tool vs alternatives (e.g., leave_group, demote_member). No prerequisites or context about admin rights are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a label from a specific WhatsApp chat
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| labelId | Yes | Label ID | |
| chatId | Yes | Chat ID to remove the label from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the removal action but does not state whether it is destructive, what side effects occur (e.g., does it affect other chats?), or any authentication or rate limit requirements.
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?
A single, clear sentence with no extraneous words. It efficiently communicates the core action without redundancy.
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 simple tool with 3 parameters and no output schema, the description provides the basic operation. However, it lacks context like required permissions, error handling, or return value. Acceptable for a straightforward action but not fully complete.
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%: each parameter (sessionId, labelId, chatId) already has a descriptive comment in the schema. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
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 clearly states the verb 'Remove', the resource 'label', and the context 'from a specific WhatsApp chat'. It distinguishes well from sibling tools like 'add_label_to_chat' (adds) and 'delete_label' (removes label entirely).
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?
No guidance on when to use this tool versus alternatives like 'add_label_to_chat' or 'delete_label'. No prerequisites or exclusions are mentioned, leaving the agent without context on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an audio file to a WhatsApp chat by providing a publicly accessible URL
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID to send from | |
| chatId | Yes | Target chat ID | |
| url | Yes | Public URL of the audio file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as authentication requirements, file size limits, success/failure responses, or that the URL must be publicly accessible (though implied).
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 single sentence with no redundant information, making it very concise and easy to parse.
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?
With no output schema and simple parameters, the description is minimally adequate but lacks context about prerequisites (e.g., active session) or error handling, which would improve completeness.
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% with descriptions for each parameter, so the description adds little extra meaning. The addition of 'publicly accessible' for the URL is the only value beyond 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?
The description clearly identifies the action (send), resource (audio file), and target (WhatsApp chat) with a condition (publicly accessible URL). However, it does not differentiate from sibling 'send_file' which could also send audio files.
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?
No guidance on when to use this tool versus alternatives like send_file or send_image. The description only states what it does, not when it should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send the same image to multiple WhatsApp recipients at once
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID to send from | |
| recipients | Yes | Array of chat IDs to send to | |
| url | Yes | Public URL of the image | |
| caption | No | Optional caption for the image |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the action without disclosing behavioral traits such as whether sending is synchronous, handling of invalid recipients, or rate limits.
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?
Single, efficient sentence with no wasted words. Front-loaded with core purpose.
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 bulk send tool with no output schema, the description leaves many gaps: no mention of return values, error handling, or that image URL must be publicly accessible. Sibling tools exist but not referenced.
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. Description adds no meaning beyond schema; e.g., 'recipients' and 'sessionId' are not elaborated.
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?
Description clearly states the verb 'Send' and resource 'same image to multiple WhatsApp recipients at once', effectively distinguishing from sibling 'send_image' which is likely for a single recipient.
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?
Description implies when to use (when sending same image to multiple recipients) but provides no when-not or alternatives, nor prerequisites like needing a valid session or contact IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send the same text message to multiple WhatsApp recipients at once
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID to send from | |
| recipients | Yes | Array of chat IDs to send to | |
| text | Yes | Message text content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description must carry full burden. Only states 'same text message' and 'at once' ā lacks details on send order, error handling, rate limits, or asynchronous behavior.
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?
Single sentence of 10 words, front-loaded with the verb. No redundancy or unnecessary information.
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 bulk operation with 3 required params and no output schema, description lacks details on failure handling, whether sending is atomic, and what the response looks like. Incomplete for effective use.
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?
Input schema covers all 3 parameters with clear descriptions (100% coverage). Description adds minimal extra meaning ('same', 'multiple') but doesn't elaborate on valid chat ID format or constraints. Baseline 3 is appropriate.
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 clearly states the verb ('Send'), resource ('same text message'), and scope ('multiple WhatsApp recipients at once'). It effectively distinguishes from sibling tools like send_text and send_bulk_image.
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?
No guidance on when to use this tool versus alternatives (e.g., send_text for single recipients). No mention of prerequisites, limitations like maximum recipients, or potential issues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a file/document to a WhatsApp chat by providing a publicly accessible URL
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID to send from | |
| chatId | Yes | Target chat ID | |
| url | Yes | Public URL of the file | |
| filename | Yes | Filename to display in the chat | |
| caption | No | Optional caption for the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the action and the need for a public URL, but omits details like required session state, file size limits, error handling, or whether the tool is destructive. This is minimal 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?
A single, well-structured sentence that is front-loaded with the main purpose. No unnecessary words.
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 simple tool with 5 parameters and no output schema, the description is adequate but lacks guidance on when to use this over other send tools. It does not explain return values or failure conditions, and the absence of annotations means the agent must infer behavior from the description alone.
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?
The input schema has 100% parameter descriptions, so the baseline is 3. The description adds slight context for the url parameter ('publicly accessible'), but does not enhance meaning for other parameters like sessionId, chatId, filename, or caption beyond 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?
The description clearly states the verb 'Send', the resource 'file/document', and the method 'by providing a publicly accessible URL'. It effectively distinguishes from sibling tools like send_image, send_video, and send_audio which are for specific media types.
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?
The description implies the tool should be used when the file is not covered by more specific media senders, but it does not explicitly state when to use send_file versus send_image, send_video, or send_audio. No alternatives or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a text message directly to a WhatsApp group
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| groupId | Yes | Group ID | |
| text | Yes | Message text content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description lacks details on permissions, rate limits, or response behavior. Minimal transparency 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?
Single sentence, no wasted words. Appropriate length for a simple action.
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?
Low complexity tool, but description omits success/failure indications and response format. With no annotations, more context is needed.
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 has 100% description coverage; parameters are sufficiently explained. Description adds no additional semantic value beyond 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?
Description clearly states it sends a text message to a WhatsApp group. Differentiates from siblings like send_text (usually to individuals) but not explicitly.
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?
No guidance on when to use this tool vs. alternatives. Does not mention prerequisites such as an active session or group membership.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an image to a WhatsApp chat by providing a publicly accessible URL
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID to send from | |
| chatId | Yes | Target chat ID | |
| url | Yes | Public URL of the image | |
| caption | No | Optional caption for the image |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose behavioral details such as whether the session must be active, side effects on the chat, rate limits, or return values. The minimal text does not compensate for the absent annotation context.
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 single, focused sentence that immediately conveys the core purpose. It is front-loaded and contains no redundant information, making it efficient for agent comprehension.
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?
Given the tool has 4 parameters, no output schema, and no annotations, the description is insufficient for an agent to understand the full operational contextāsuch as expected outputs, error conditions, or lifecycle (e.g., does it wait for send confirmation?).
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?
Although the input schema has 100% coverage with clear parameter descriptions, the tool description adds no additional meaning beyond restating the URL requirement. Baseline is met but no extra value is provided.
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 clearly states the action ('send an image') and context ('to a WhatsApp chat'), and specifies the mechanism ('publicly accessible URL'), which effectively distinguishes it from sibling tools like send_video or upload_media.
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?
No guidance is provided on when to use this tool vs. alternatives (e.g., upload_media for private images), nor prerequisites like requiring an active session or valid chat ID. This lack of usage direction increases the risk of incorrect tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a text message to a WhatsApp chat. chatId format: 5511999999999@c.us for contacts or 5511999999999-1234567890@g.us for groups.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID to send from | |
| chatId | Yes | Target chat ID | |
| text | Yes | Message text content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, and the description does not disclose behavioral aspects such as idempotency, side effects, error handling, or rate limits. The description only states the action, missing critical transparency for a send operation.
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?
Two sentences, no redundant information. Every word serves a purpose, making it concise and easy to parse.
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?
Given the tool's simplicity (three required params, no output schema), the description covers the essential action and chat ID format. However, it lacks information on response behavior or potential errors, and does not differentiate from sibling tools like send_bulk_text, leaving some context gaps.
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 already describes all three parameters (100% coverage). The description adds value by explaining the chatId format (e.g., '@c.us' for contacts, '@g.us' for groups), which is beyond the schema description. This extra detail enhances parameter understanding.
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?
Clearly states the action 'send a text message' and the specific resource 'WhatsApp chat'. Distinguishes from siblings like send_image by focusing solely on text. Also provides essential chat ID format, enhancing clarity.
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?
Does not explicitly state when to use this tool versus alternatives like send_bulk_text or send_group_message. However, the context of sending a single text message is implied, and the chat ID format is provided, aiding correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a video to a WhatsApp chat by providing a publicly accessible URL
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID to send from | |
| chatId | Yes | Target chat ID | |
| url | Yes | Public URL of the video | |
| caption | No | Optional caption for the video |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description only states the action without revealing important traits like required authentication, error handling for invalid URLs, or whether the operation is synchronous. This is insufficient for a mutation-like 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?
A single, front-loaded sentence that directly states the tool's purpose and a key requirement. No unnecessary words or repetition.
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?
Given the low complexity and full schema coverage, the description is adequate but leaves gaps. It fails to mention that a valid session must exist, what happens on failure (e.g., non-public URL), or how it differs from send_file which can also send videos. Annotations are missing, so the description should provide more behavioral context.
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?
With 100% schema description coverage, the description adds minimal value beyond the schema. It clarifies that the URL must be 'publicly accessible' and notes that 'caption' is optional, but this information is already implicit or stated in the schema. Baseline of 3 is appropriate.
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 clearly states the verb 'send' and resource 'video' to a specific target 'WhatsApp chat' with the constraint 'by providing a publicly accessible URL'. This distinctly separates it from sibling tools like send_image or send_file.
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?
The description implies the tool is for sending videos via a public URL, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., send_file for other media types, send_bulk_image for images). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a stopped WhatsApp session to make it active
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | ID of the session to start |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It states the core action but omits details like what happens if the session is already active, if it doesn't exist, or any preconditions (e.g., QR scan required).
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?
Single sentence, no wasted words, appropriately sized for a simple tool.
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?
Given the simplicity of the tool (1 param, no output schema), the description is minimally adequate but lacks context about session state management and potential failures.
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 covers 100% of parameters with a description for sessionId; the tool description adds no extra meaning, but schema already provides adequate information.
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?
Description clearly specifies the action ('Start') and the resource ('stopped WhatsApp session'), distinguishing it from sibling tools like create_session or stop_session.
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?
The description implies usage for stopped sessions, but no explicit guidance on when to use this vs. other session-related tools (e.g., create_session, get_session_status) is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running WhatsApp session gracefully
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | ID of the session to stop |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. 'Gracefully' hints at clean shutdown but lacks details on side effects, error handling, or prerequisites (e.g., session must be running).
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?
A single, concise sentence. No wasted words, but could include more behavioral context without losing brevity.
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?
Adequate for a simple tool with one parameter and no output schema, but lacks behavioral details that would help the agent use 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%, so the description adds no extra meaning beyond 'ID of the session to stop'. Baseline 3 is appropriate.
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 uses a specific verb ('Stop') and resource ('running WhatsApp session'), clearly distinguishing from sibling tools like 'delete_session' and 'start_session'.
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?
No guidance on when to use this tool over alternatives (e.g., 'delete_session'). The agent must infer context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unblock a previously blocked WhatsApp contact
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| contactId | Yes | Contact ID to unblock |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover safety and side effects. Only states 'Unblock a previously blocked contact' without disclosing idempotency, error handling (e.g., if already unblocked), or permissions needed.
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?
Single sentence is concise. However, it could be structured with more detail (e.g., separate line for precondition) without sacrificing brevity.
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?
Adequate for a simple tool. However, no output schema or mention of return value. Could include note on what happens on success/failure.
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% with basic field descriptions. The description adds the key context that the contact was 'previously blocked', which reinforces the tool's purpose beyond 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?
Description clearly states the verb 'Unblock' and resource 'WhatsApp contact'. It directly conveys the action of reversing a previous block, distinguishing it from sibling tool 'block_contact'.
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?
No guidance on when to use or prerequisites. It's straightforward, but could mention that the contact must be currently blocked. No alternatives discussed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the name/subject of a WhatsApp group
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| groupId | Yes | Group ID | |
| subject | Yes | New group name/subject |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It only states the action, omitting any behavioral traits such as whether the change is reversible, if other members are notified, or if any validation occurs (e.g., group existence).
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 single sentence, no redundant words, and the action is immediately clear. It is appropriately concise.
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?
Given no output schema and no annotations, the description is too sparse. It does not mention return values, error conditions, or preconditions (e.g., the group must exist and the session must be active). A mutation tool of this nature requires more contextual information for an AI agent to use 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 description coverage is 100%, so baseline is 3. The description adds minimal meaning beyond the schema, primarily linking the 'subject' parameter to the tool's purpose. It does not clarify the format or constraints on the 'sessionId' and 'groupId' parameters.
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 clearly states the action ('Change') and the resource ('name/subject of a WhatsApp group'), using a specific verb and resource combination that distinguishes this tool from siblings like 'create_group' or 'add_group_member'.
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?
No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites (e.g., group ownership or admin rights). The description lacks both positive and negative usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing webhook configuration
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| webhookId | Yes | Webhook ID to update | |
| url | No | New webhook endpoint URL | |
| events | No | Updated event types | |
| secret | No | Updated signing secret |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Update an existing webhook configuration' without disclosing side effects, required permissions, or immediate effects. This is insufficient 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 single sentence, which is concise. However, it is too minimal and lacks structure; it could benefit from additional detail without becoming verbose.
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?
The tool has no output schema and no annotations. The description does not mention return values, success/failure behavior, or what happens after an update. For a mutation tool, this leaves significant gaps.
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?
With 100% schema description coverage, the schema already documents each parameter. The description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
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 clearly identifies the verb 'Update' and the resource 'webhook configuration', distinguishing it from siblings like create_webhook, delete_webhook, and list_webhooks. However, it could be more specific about which fields can be updated.
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?
No guidance on when to use this tool versus alternatives, such as creating a new webhook or deleting one. There is no mention of prerequisites (e.g., existing webhook ID) or scenarios where update is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload media to OpenWA for later use in messages
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID | |
| file | Yes | Public URL of the media file to upload | |
| type | Yes | Media type: image, video, audio, or document |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist. The description only says 'Upload media', which indicates mutation but lacks details on behavior such as size limits, overwrite rules, or storage duration.
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?
Single sentence, 8 words, very concise. However, it could be slightly more structured by front-loading the verb and resource, but it is not verbose.
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?
Given the presence of many sibling tools and no output schema or annotations, the description is incomplete. It does not explain return values, prerequisites, or constraints (e.g., file URL accessibility).
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?
The input schema has 100% description coverage, so the description adds no additional meaning beyond the schema's parameter descriptions. Baseline score of 3 is appropriate.
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 clearly states the verb 'Upload' and the resource 'media to OpenWA for later use in messages', distinguishing it from siblings like send_image or get_media.
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?
The description implies that upload is a prerequisite for sending media messages, but does not explicitly state when to use it versus alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0add_group_memberadd_label_to_chatblock_contactcheck_numbercreate_groupcreate_labelcreate_sessioncreate_webhookdelete_labeldelete_messagedelete_sessiondelete_webhookdemote_memberget_contactget_contactsget_group_infoget_groupsget_labelsget_mediaget_messagesget_profile_pictureget_session_qrget_session_statusget_sessionsleave_grouplist_webhookspromote_memberreact_to_messageremove_group_memberremove_label_from_chatsend_audiosend_bulk_imagesend_bulk_textsend_filesend_group_messagesend_imagesend_textsend_videostart_sessionstop_sessionunblock_contactupdate_group_subjectupdate_webhookupload_mediaScored across 44 tools
Most tools have distinct purposes, but there is overlap between send_text and send_group_message as both can send text to groups. Other tools are clearly separated by resource or action.
All tools follow a consistent verb_noun pattern with underscores (e.g., add_group_member, block_contact). No mixing of styles or irregular naming.
With 44 tools, the server is overly large for its scope. Many operations could be combined (e.g., send_bulk_text and send_bulk_image could share a parameter), exceeding the recommended maximum of 25.
The tool set covers all major WhatsApp operations: sessions, contacts, groups, messaging (including media and bulk), labels, and webhooks. No obvious gaps for typical use cases.
WhatsApp CRM for AI agents: search contacts, read chats, manage the sales pipeline, send messages.
Run WhatsApp Business campaigns from any AI assistant: contacts, segments, and broadcasts.
Give your AI agents a real WhatsApp number to send and receive messages.
Messaging tools for AI agents: send messages, manage chats, groups and channels.
