wazap-mcp

Read messages from a WhatsApp chat

read_messages

Read-onlyIdempotent

Retrieve messages from a WhatsApp chat, newest or older via before, with optional full text; use chat_id "status" to read recent stories.

Instructions

Read one chat, oldest to newest: the latest messages, or older ones with before (wazap asks the phone when the local history runs out). Long texts are cut unless full_text. chat_id "status" reads the stories people posted, newest first, from the last hours (at most a day); they show nowhere else.

Input Schema

Name	Required	Description
`hours`	No	"status" only: how far back, 24 by default
`limit`	No
`types`	No	Only these types; limit counts them, so ["call"] gives that many calls
`before`	No	The oldest message_id you have
`chat_id`	Yes	Chat id from another tool, a phone number, or "status" for stories
`full_text`	No	Each message's text whole; a list cuts long ones otherwise
`account_id`	No
`include_previews`	No	Attach a small image of each photo, up to 12

Output Schema

Name	Required	Description
`sync`	Yes
`count`	Yes
`hours`	No
`notes`	No	Caveats to act on or tell the user
`older`	No	before ran past the local history: the phone was asked, and sent this many
`types`	No
`chat_id`	Yes
`omitted`	No	Older stories left out by limit
`messages`	Yes
`account_id`	Yes
`preview_count`	Yes
`unconfirmed_sends`	No	Sends WhatsApp has not echoed yet: outcome unknown, not failed

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.6.0Oct 22, 2026
- removedInput schema / properties / account_id / description
```
Removed value: -"Account id"
```

Changed1 schema field changedv1.4.0Oct 15, 2026

addedInput schema / properties / full_text

Added value: +{
+  "description": "Each message's text whole; a list cuts long ones otherwise",
+  "type": "boolean"
+}

Changed8 schema fields changedv1.0.3Sep 23, 2026

changedInput schema / properties / account_id / description

Previous value: -"Registry account id (default, work, …). Omit to resolve from chat_id or message_id, or the default account."New value: +"Account id"

changedInput schema / properties / before / description

Previous value: -"Return the messages immediately older than this message_id"New value: +"The oldest message_id you have"

changedInput schema / properties / chat_id / description

Previous value: -"Chat id as returned by another tool (\"<digits>@s.whatsapp.net\" or \"<id>@g.us\"), or a phone number in international format"New value: +"Chat id from another tool, a phone number, or \"status\" for stories"

addedInput schema / properties / hours

Added value: +{
+  "description": "\"status\" only: how far back, 24 by default",
+  "maximum": 24,
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / include_previews / description

Previous value: -"Attach a small JPEG of each photo, newest first, up to 12 per call, so you can see what was sent: the preview WhatsApp shipped when there is one, otherwise the photo is downloaded once and shrunk on the machine running wazap"New value: +"Attach a small image of each photo, up to 12"

removedInput schema / properties / limit / description

Removed value: -"Maximum number of messages (1-200)"

changedInput schema / properties / types / description

Previous value: -"Keep only these message types; omit for every type. The limit counts matching messages, so [\"call\"] returns that many calls, not that many messages of which some are calls."New value: +"Only these types; limit counts them, so [\"call\"] gives that many calls"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "account_id": {
+      "type": "string"
+    },
+    "chat_id": {
+      "type": "string"
+    },
+    "count": {
+      "type": "number"
+    },
+    "hours": {
+      "type": "number"
+    },
+    "messages": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "chat_id": {
+            "type": "string"
+          },
+          "message_id": {
+            "type": "string"
+          },
+          "private": {
+            "const": true,
+            "description": "Tagged #private: no words",
+            "type": "boolean"
+          },
+          "text": {
+            "type": "string"
+          },
+          "timestamp": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "message_id",
+          "chat_id",
+          "text",
+          "timestamp"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "notes": {
+      "description": "Caveats to act on or tell the user",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "older": {
+      "additionalProperties": false,
+      "description": "before ran past the local history: the phone was asked, and sent this many",
+      "properties": {
+        "asked_phone": {
+          "const": true,
+          "type": "boolean"
+        },
+        "received": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "asked_phone",
+        "received"
+      ],
+      "type": "object"
+    },
+    "omitted": {
+      "description": "Older stories left out by limit",
+      "type": "number"
+    },
+    "preview_count": {
+      "type": "number"
+    },
+    "sync": {
+      "type": "string"
+    },
+    "types": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "unconfirmed_sends": {
+      "description": "Sends WhatsApp has not echoed yet: outcome unknown, not failed",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "draft_id": {
+            "type": "string"
+          },
+          "handed_at": {
+            "type": "string"
+          },
+          "state": {
+            "const": "unknown",
+            "type": "string"
+          },
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "draft_id",
+          "text",
+          "handed_at",
+          "state"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "chat_id",
+    "count",
+    "preview_count",
+    "messages",
+    "sync",
+    "account_id"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.21.0Sep 16, 2026

changedInput schema / properties / types / items / enum

Previous value: -[
-  "text",
-  "image",
-  "video",
-  "audio",
-  "voice",
-  "document",
-  "sticker",
-  "location",
-  "contact",
-  "poll",
-  "reaction",
-  "deleted",
-  "view_once",
-  "call",
-  "system",
-  "unknown"
-]New value: +[
+  "text",
+  "image",
+  "video",
+  "audio",
+  "voice",
+  "document",
+  "sticker",
+  "location",
+  "contact",
+  "poll",
+  "reaction",
+  "deleted",
+  "view_once",
+  "call",
+  "event",
+  "invite",
+  "system",
+  "unknown"
+]

Changed2 schema fields changedv0.15.0Sep 12, 2026

addedInput schema / properties / account_id

Added value: +{
+  "description": "Registry account id (default, work, …). Omit to resolve from chat_id or message_id, or the default account.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / include_previews

Added value: +{
+  "default": false,
+  "description": "Attach a small JPEG of each photo, newest first, up to 12 per call, so you can see what was sent: the preview WhatsApp shipped when there is one, otherwise the photo is downloaded once and shrunk on the machine running wazap",
+  "type": "boolean"
+}

Changed1 schema field changedv0.10.0Aug 23, 2026

addedInput schema / properties / types

Added value: +{
+  "description": "Keep only these message types; omit for every type. The limit counts matching messages, so [\"call\"] returns that many calls, not that many messages of which some are calls.",
+  "items": {
+    "enum": [
+      "text",
+      "image",
+      "video",
+      "audio",
+      "voice",
+      "document",
+      "sticker",
+      "location",
+      "contact",
+      "poll",
+      "reaction",
+      "deleted",
+      "view_once",
+      "call",
+      "system",
+      "unknown"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

First observedv0.9.3Aug 23, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already establish readOnly/idempotent/openWorld, and the description adds real behavior the annotations don't: history gaps trigger a phone fetch (latency/implication), long texts are truncated unless full_text, and status items are ephemeral (max a day) and appear nowhere else. It does not cover error modes or rate limits, so not a full 5.

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 and front-loaded, with the main retrieval model in the first clause and the status special case after. The prose is slightly idiosyncratic ("wazap asks the phone") but every sentence carries information, so nothing is wasteful.

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

Completeness4/5

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

Given an output schema exists and annotations cover the safety profile, the description covers the non-obvious essentials: pagination, truncation, and the stories mode. The main gap is account_id (multi-account selection), which is undocumented in both the schema and the description.

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?

With 75% schema coverage the baseline is 3, and the description genuinely adds value: it explains the before-based pagination model, the truncation default that full_text overrides, and that "status" is a special chat_id value. `limit`, `types` and `account_id` are left to the schema (account_id is undescribed in both places).

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?

Opens with a specific verb and resource plus scope: "Read one chat, oldest to newest." It also carves out the special "status" mode for stories, which an agent could not infer from the name. Together these let an agent tell it apart from search, get_message, list_chats and wait_for_messages.

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

Usage Guidelines4/5

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

Clear context for the two main modes: fetch the latest messages, or page backwards using `before` once you have the oldest message_id. It also flags that stories require chat_id "status" and are time-bounded. It stops short of explicitly naming when to prefer search, catch_up or wait_for_messages instead.

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