Skip to main content
Glama

whatsmcp

by com.whatsmcp
OverviewDiscussionsAdmin

Pair Account

wa_pair_account

Begin linking a new WhatsApp account. There are two ways to link and the right one depends on the user's devices, so ASK FIRST: if they can scan a QR code from another screen (a second phone, or this computer's screen) using the WhatsApp app on their phone, call this with no phone and show the returned QR PNG; if they only have the one phone that runs WhatsApp — it cannot scan its own screen — pass phone in international format to get an 8-character code they type on that phone instead. Then poll wa_pair_status with the returned pair_id: a QR re-arms about every 20 seconds (show the newest each time), a phone code lasts a few minutes, and either way the state turns "paired" once it is linked. Pass import_history to choose whether this pairing loads the phone's recent messages as history.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
phoneNolink by phone-number code instead of a QR: the number to link, in international format with its country code (for example +52 998 123 4567). WhatsApp on that phone is asked to accept an 8-character code, returned as pair_code. Use it when the user has only the one phone that runs WhatsApp and cannot scan a QR from another screen
import_historyNoimport the phone's recent message history (about two months) as read-only history for this pairing; omit to use the workspace default

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
stateYesstarting, qr, code, paired or failed
pair_idNopass this to wa_pair_status to follow the pairing
refusalNopresent only when pairing could not be started
pair_codeNothe 8-character code the user types on their phone (phone-number pairing only)
expires_atNowhen pair_code stops working, RFC 3339 (phone-number pairing only)
needs_planNotrue when the linked number has no plan yet and will not run until the user buys one in the console
instructionsNowhat to tell the user to do
qr_png_base64Noa PNG image of the QR code, base64 encoded — display this to the user

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / phone / description
      Previous value: -"link by phone-number code instead of a QR: the number to link, in international format with its country code (for example +52 998 123 4567). WhatsApp on that phone is asked to accept an 8-character code, returned as pair_code. Use it when the user has only that phone and cannot scan a QR"New value: +"link by phone-number code instead of a QR: the number to link, in international format with its country code (for example +52 998 123 4567). WhatsApp on that phone is asked to accept an 8-character code, returned as pair_code. Use it when the user has only the one phone that runs WhatsApp and cannot scan a QR from another screen"
  2. Changed7 schema fields changed
    • addedInput schema / properties / phone
      Added value: +{
+  "description": "link by phone-number code instead of a QR: the number to link, in international format with its country code (for example +52 998 123 4567). WhatsApp on that phone is asked to accept an 8-character code, returned as pair_code. Use it when the user has only that phone and cannot scan a QR",
+  "type": "string"
+}
    • addedOutput schema / properties / expires_at
      Added value: +{
+  "description": "when pair_code stops working, RFC 3339 (phone-number pairing only)",
+  "type": "string"
+}
    • addedOutput schema / properties / pair_code
      Added value: +{
+  "description": "the 8-character code the user types on their phone (phone-number pairing only)",
+  "type": "string"
+}
    • addedOutput schema / properties / refusal / properties / account_status
      Added value: +{
+  "description": "when the number is not working: its status — starting, not_running, whatsapp_down, suspended, pairing, unlinked or locked",
+  "type": "string"
+}
    • addedOutput schema / properties / refusal / properties / account_status_reason
      Added value: +{
+  "description": "the detail of account_status, e.g. no_egress, stopped, no_plan",
+  "type": "string"
+}
    • addedOutput schema / properties / refusal / properties / since
      Added value: +{
+  "description": "when the number stopped working, RFC3339, when known",
+  "type": "string"
+}
    • changedOutput schema / properties / state / description
      Previous value: -"starting, qr, paired or failed"New value: +"starting, qr, code, paired or failed"
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only cover the mutation/safety profile (readOnly=false, idempotent=false, destructive=false); the description adds the timing semantics that matter operationally — QR re-arms ~every 20 seconds, phone code lasts a few minutes, and state transitions to 'paired'. It also discloses that import_history loads ~two months of recent messages.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but earns its length: the QR-first instruction and the branch condition are front-loaded, and every clause carries actionable detail. It reads as one long paragraph, so light structural friction remains, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be restated, yet the description still tells the agent what comes back (QR PNG, pair_code, pair_id) and what to do next. For a multi-step pairing flow this is effectively complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine conditional meaning: phone is only for the single-device case and yields an 8-character pair_code, while omitting it produces a QR PNG; import_history controls history loading. Format guidance (+52 998 123 4567) is repeated from the schema but the decision logic is new.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Begin linking a new WhatsApp account') and is clearly delineated from siblings wa_pair_status (polling) and wa_unpair_account (teardown). An agent can identify the tool's role without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'ASK FIRST' and then branches on device context: QR when another screen can scan, phone code when only one phone exists. It also names the follow-up tool (wa_pair_status) and the selection criterion, leaving nothing to inference.

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

All whatsmcp toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources