Skip to main content
Glama
wazap-mcp

wazap-mcp

by razvangirgiz

Read messages from a WhatsApp chat

read_messages
Read-onlyIdempotent

Retrieves messages from a single WhatsApp chat, oldest to newest, with options for latest, older via before, date windows, or status stories.

Instructions

Read one chat, oldest to newest: the latest messages, older ones with before (wazap asks the phone when the local history runs out), or a window with since/until. Long texts are cut unless full_text. chat_id "status": the stories of the last hours (a day at most), shown nowhere else.

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": {
      "chat_id": "<chat_id>"
    },
    "name": "read_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
hoursNoThe last N hours; "status": 24 by default
limitNo
sinceNoISO date or time
typesNoOnly these types; limit counts them
untilNoISO date or time
beforeNoThe oldest message_id you have
chat_idYesChat id, number or name (one chat only); "status": stories
full_textNoEach message's text whole; a list cuts long ones otherwise
account_idNo
include_previewsNoAttach a small image of each photo, up to 6

Output Schema

NameRequiredDescriptionDefault
syncYes
countYes
hoursNo
notesNoCaveats to act on or tell the user
olderNobefore ran past the local history: the phone was asked, and sent this many
sinceNoThe window asked for, as read
typesNo
untilNo
chat_idYes
omittedNoOlder stories left out by limit
messagesYes
previewsNoThe message_id of each attached image, in their order
resolvedNochat_id was a name: the chat it resolved to
account_idYes
preview_countYes
more_in_windowNoThe window holds older messages than these: page on with before
unconfirmed_sendsNoSends WhatsApp has not echoed yet: outcome unknown, not failed

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changedv1.7.4
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • changedInput schema / properties / chat_id / description
      Previous value: -"Chat id from another tool, a phone number, or \"status\" for stories"New value: +"Chat id, number or name (one chat only); \"status\": stories"
    • changedInput schema / properties / hours / description
      Previous value: -"\"status\" only: how far back, 24 by default"New value: +"The last N hours; \"status\": 24 by default"
    • changedInput schema / properties / include_previews / description
      Previous value: -"Attach a small image of each photo, up to 12"New value: +"Attach a small image of each photo, up to 6"
    • addedInput schema / properties / since
      Added value: +{
      +  "description": "ISO date or time",
      +  "minLength": 4,
      +  "type": "string"
      +}
    • changedInput schema / properties / types / description
      Previous value: -"Only these types; limit counts them, so [\"call\"] gives that many calls"New value: +"Only these types; limit counts them"
    • addedInput schema / properties / until
      Added value: +{
      +  "description": "ISO date or time",
      +  "minLength": 4,
      +  "type": "string"
      +}
    • removedOutput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • changedOutput schema / properties / messages / items / additionalProperties
      Previous value: -trueNew value: +{}
    • addedOutput schema / properties / more_in_window
      Added value: +{
      +  "const": true,
      +  "description": "The window holds older messages than these: page on with before",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / previews
      Added value: +{
      +  "description": "The message_id of each attached image, in their order",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / resolved
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "chat_id was a name: the chat it resolved to",
      +  "properties": {
      +    "from": {
      +      "type": "string"
      +    },
      +    "kind": {
      +      "enum": [
      +        "person",
      +        "group"
      +      ],
      +      "type": "string"
      +    },
      +    "name": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "from",
      +    "name",
      +    "kind"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / since
      Added value: +{
      +  "description": "The window asked for, as read",
      +  "type": "string"
      +}
    • addedOutput schema / properties / until
      Added value: +{
      +  "type": "string"
      +}
  2. Changed1 schema field changedv1.6.0
    • removedInput schema / properties / account_id / description
      Removed value: -"Account id"
  3. Changed1 schema field changedv1.4.0
    • addedInput schema / properties / full_text
      Added value: +{
      +  "description": "Each message's text whole; a list cuts long ones otherwise",
      +  "type": "boolean"
      +}
  4. Changed8 schema fields changedv1.0.3
    • 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"
      +}
  5. Changed1 schema field changedv0.21.0
    • 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"
      +]
  6. Changed2 schema fields changedv0.15.0
    • 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"
      +}
  7. Changed1 schema field changedv0.10.0
    • 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"
      +}
  8. First observedv0.9.3

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavior beyond them: ordering is oldest-to-newest, `before` takes the oldest message_id you hold (a pagination contract), history may be fetched from the phone causing latency, long texts are truncated unless full_text, and the "status" pseudo-chat only holds a day or less of stories. These are non-obvious operational facts an agent would otherwise discover by failing.

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 front-loaded: the core operation and its modes come first, then caveats (truncation, status semantics). Every clause carries information. The telegraphic style, especially the quoted "status" fragment at the end, is slightly harder to parse than plain sentences but wastes no words.

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?

With 10 parameters, an output schema, and full annotation coverage, the description covers the operation, all three modes, pagination semantics, truncation, and the status special case. Remaining gaps are minor: account_id is unexplained, and the interaction between `hours` and since/until is not clarified. Return values need not be described given the output schema.

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

Parameters3/5

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

Schema coverage is already 80%, so the baseline is 3 and the schema documents limit, types, hours, include_previews and since/until. The description does add real meaning for `before` ('the oldest message_id you have') and `full_text` (truncation behavior otherwise), and explains the "status" value of chat_id. It says nothing about account_id or how `hours` interacts with `since`/`until`, leaving some ambiguity.

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

Purpose4/5

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

States a specific verb and resource ('Read one chat, oldest to newest') and enumerates its three retrieval modes (latest, older via before, window via since/until), plus the special "status" chat for stories. An agent can immediately tell this is a single-chat message reader. It does not name a sibling (e.g. get_message, search, wait_for_messages), so differentiation is behavioral rather than explicit.

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?

Explicitly maps parameter choices to retrieval intents: default latest messages, `before` for paging backwards, `since`/`until` for a time window, and chat_id "status" for stories only. It also warns that `before` may trigger a phone round-trip when local history is exhausted, which shapes when the call is cheap. No guidance on when to prefer this over get_message or search, and no exclusions stated.

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