wazap-mcp

Search WhatsApp messages

search

Read-onlyIdempotent

Find WhatsApp messages by meaning or exact words, with nearby context and citations, using queries, dates, tags, people, and chat filters.

Instructions

Find by meaning and words, with nearby source contexts. Use the question and known context, never guessed filters. Auto: exact codes/quoted literals; words: substrings. Check corrections; assessment flags ambiguity. Cite the supporting message.

Input Schema

Name	Required	Description	Default
`tag`	No	Only chats with people filed under this tag
`from`	No	"me", a number, an id, or a name only one person has
`limit`	No
`match`	No	auto: questions by meaning, codes/quotes by words	auto
`query`	Yes
`since`	No	ISO date or time
`until`	No	ISO date or time
`before`	No	Older lexical matches; auto uses words with a cursor
`chat_id`	No	Chat id, or a phone number
`full_text`	No	Each message's text whole; a list cuts long ones otherwise
`account_id`	No
`include_context`	No	Nearby sources for the best five hits

Output Schema

Name	Required	Description
`mode`	Yes	keyword_fallback: meaning search could not run, see recall_unavailable
`sync`	Yes
`count`	Yes
`index`	No
`notes`	No	Caveats to act on or tell the user
`query`	Yes
`contexts`	No
`coverage`	No	null: it could not be counted
`messages`	Yes
`freshness`	Yes
`account_id`	Yes
`assessment`	Yes
`next_before`	No
`scan_capped`	No	Older matches may be missing: narrow the search
`from_resolved`	No
`private_omitted`	No	Matches from people tagged #private, left out: chat_id or from shows them
`searched_back_to`	No	Older messages were not searched: narrow the search
`recall_unavailable`	No
`changed_during_read`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed21 schema fields changedv1.6.0Oct 22, 2026

removedInput schema / properties / account_id / description
```
Removed value: -"Account id"
```

addedInput schema / properties / before

Added value: +{
+  "description": "Older lexical matches; auto uses words with a cursor",
+  "minLength": 5,
+  "type": "string"
+}

addedInput schema / properties / include_context

Added value: +{
+  "default": true,
+  "description": "Nearby sources for the best five hits",
+  "type": "boolean"
+}

changedInput schema / properties / match / default
```
Previous value: -"hybrid"New value: +"auto"
```

changedInput schema / properties / match / description

Previous value: -"\"words\": only messages holding the words"New value: +"auto: questions by meaning, codes/quotes by words"

changedInput schema / properties / match / enum

Previous value: -[
-  "hybrid",
-  "words"
-]New value: +[
+  "auto",
+  "hybrid",
+  "words"
+]

addedInput schema / properties / tag

Added value: +{
+  "description": "Only chats with people filed under this tag",
+  "maxLength": 40,
+  "minLength": 1,
+  "type": "string"
+}

addedOutput schema / properties / assessment

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "note": {
+      "type": "string"
+    },
+    "state": {
+      "enum": [
+        "no_matches",
+        "ambiguous",
+        "candidates"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "state",
+    "note"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / changed_during_read
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / contexts

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "anchor_id": {
+        "type": "string"
+      },
+      "bounded": {
+        "const": true,
+        "type": "boolean"
+      },
+      "messages": {
+        "items": {
+          "additionalProperties": true,
+          "properties": {
+            "chat_id": {
+              "type": "string"
+            },
+            "message_id": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            },
+            "timestamp": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "message_id",
+            "chat_id",
+            "text",
+            "timestamp"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "anchor_id",
+      "messages",
+      "bounded"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / messages / items / properties / chat_id / $ref

Added value: +"#/properties/contexts/items/properties/messages/items/properties/chat_id"

removedOutput schema / properties / messages / items / properties / chat_id / type
```
Removed value: -"string"
```

addedOutput schema / properties / messages / items / properties / message_id / $ref

Added value: +"#/properties/contexts/items/properties/messages/items/properties/message_id"

removedOutput schema / properties / messages / items / properties / message_id / type
```
Removed value: -"string"
```
addedOutput schema / properties / messages / items / properties / rank_score
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / messages / items / properties / text / $ref

Added value: +"#/properties/contexts/items/properties/messages/items/properties/text"

removedOutput schema / properties / messages / items / properties / text / type
```
Removed value: -"string"
```

addedOutput schema / properties / messages / items / properties / timestamp / $ref

Added value: +"#/properties/contexts/items/properties/messages/items/properties/timestamp"

removedOutput schema / properties / messages / items / properties / timestamp / type
```
Removed value: -"string"
```

addedOutput schema / properties / next_before

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "mode",
-  "count",
-  "messages",
-  "freshness",
-  "sync",
-  "account_id"
-]New value: +[
+  "query",
+  "mode",
+  "count",
+  "assessment",
+  "messages",
+  "freshness",
+  "sync",
+  "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"
+}

Addedv1.0.3Sep 23, 2026

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real behavioral signal beyond that: results include nearby source contexts, come with 'corrections', and carry an 'assessment' that flags ambiguity — though it never says what these look like or how large results are.

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

Conciseness3/5

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

It is short and contains no filler, but the telegraphic fragments ('Check corrections; assessment flags ambiguity') and the trailing agent instruction 'Cite the supporting message' make it read as shorthand notes rather than front-loaded prose. Compact but choppy and harder to parse than necessary.

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

Completeness3/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 no explanation, and annotations carry the safety profile. However, for a 12-parameter search tool the description leaves the time filters, cursor paging via 'before', and account scoping entirely to the schema, so it is only adequately complete.

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 75% with 12 parameters, so the baseline is 3. The description does add meaning for 'match' ('words: substrings', exact codes/quoted literals) and rules out guessed tag/from filters, but it says nothing about limit, since/until, chat_id, account_id, full_text, or the 'before' cursor.

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?

The verb 'Find' plus 'by meaning and words' establishes this as a hybrid semantic/lexical message search, which is distinct from read_messages or list_chats. The resource (messages) is only implicit via the title, so it is clear but not fully self-contained.

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

Usage Guidelines3/5

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

'Use the question and known context, never guessed filters' gives a query-construction rule, and the auto/words split hints at mode choice, but there is no explicit when-to-use-this-vs-siblings guidance (e.g. versus get_message or read_messages). Usage is implied rather than stated.

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