Skip to main content
Glama

Connect a WhatsApp number

connect_whatsapp_number
Idempotent

Connect a WhatsApp number to the user's Werify account by pairing code — no QR, no browser. Ask the user for their WhatsApp number with country code (never infer it), call this, then relay the instructions: the phone gets a WhatsApp notification to link a device, or the user opens WhatsApp → Linked devices → Link a device → Link with phone number, and types the code. The code is valid for about 2.5 minutes; if it expires, call again for a new one. Where Werify's pairing widget shows, qr: true shows a QR code to scan with the phone instead, for a user who asks to scan one.

The pairing completes on the phone, not here: confirm it with list_connected_numbers (linking → syncing → ready). A number the user had connected before and that dropped is reconnected in place (reconnecting: true) — nothing is lost. Connecting is free. Once capture_funded is true, capture can start here through list_capturable_chats and start_live_capture. A number linked to another Werify account is refused without revealing that account; the user moves it to this account in the web app. If this tool answers an error whose code is currency_selection_required, the user has not confirmed the account's currency: show them the action_url and do not retry until they say it is done.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "phone": "<phone>"
    },
    "name": "connect_whatsapp_number"
  }
}

Input Schema

NameRequiredDescriptionDefault
qrNoSet to true to show a QR code to scan instead of a pairing code, when the user asks to scan one. Only where Werify's pairing widget shows, because the widget draws it.
phoneYesThe user's WhatsApp number with country code, e.g. "+55 11 91234-5678". Ask the user for it; never guess it.

Output Schema

NameRequiredDescriptionDefault
qrNoTrue when Werify's pairing widget shows a QR code to scan instead of a code. The widget reads it from list_connected_numbers as WhatsApp replaces it.
phoneNoThe number being connected, in international format.
localeNoThe Werify account's language as a BCP 47 tag, for the widget's own text.
help_urlNoA page showing the WhatsApp screens step by step, in the user's language.
expires_atNoWhen it stops working, as an ISO 8601 UTC timestamp.
instructionsNoWhat to tell the user, step by step. Relay it; translate if needed.
pairing_codeNoThe 8-character code the user types into WhatsApp. Absent when qr is true.
reconnectingNoTrue when this number was connected before and is being re-paired in place.
expires_in_secondsNoHow long the code, or the run of QR codes, stays valid (about 160 s).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (which only cover mutation/open-world/idempotency), it discloses the 2.5-minute code expiry and the retry-on-expiry behavior, that pairing completes out-of-band on the phone, the `linking` → `syncing` → `ready` state progression, that previously connected numbers reconnect in place (`reconnecting: true`), that the operation is free, and that a number linked to another account is refused without disclosure. It also specifies exact error handling for `currency_selection_required` with an `action_url` and a do-not-retry rule — behavior an agent could not infer from any structured field.

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?

It is long but front-loaded and well ordered: what it does, how to call it, what the user does on the phone, how to confirm, then edge cases and errors. Nearly every sentence carries actionable detail, though the second paragraph packs several unrelated concerns (funding, cross-account refusal, currency error) that could be split for faster scanning.

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?

For a multi-step, out-of-band, human-in-the-loop pairing flow, the description covers prerequisites, user-facing relay instructions, timeouts, verification path, idempotent reconnect semantics, and a specific recoverable error contract. An output schema exists, so return values need no explanation, and nothing an agent needs to invoke or recover from this tool correctly is missing.

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% and both parameters are already described, so the baseline is 3. The description nonetheless adds operational meaning beyond the schema: `qr: true` is gated on 'where Werify's pairing widget shows, because the widget draws it,' and the phone parameter carries the hard constraint 'never infer it,' which reinforces the never-guess rule at the decision level rather than just the field level.

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?

The opening sentence states the exact verb, resource, and mechanism: 'Connect a WhatsApp number to the user's Werify account by pairing code — no QR, no browser.' It simultaneously distinguishes the default path from the QR path, so the agent knows what this tool does and how it differs from scanning-based flows.

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?

Explicit preconditions are given ('Ask the user for their WhatsApp number with country code (never infer it)'), along with the follow-on step (relay `instructions`) and the completion-check path via `list_connected_numbers`. It also names the specific condition that selects the alternative parameter: '`qr: true` shows a QR code ... for a user who asks to scan one.'

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources