groupme-mcp-server

Search Messages

search_messages

Read-onlyIdempotent

Search a conversation's message history to find specific messages by text or sender name, avoiding manual paging. Returns matches and scan progress.

Instructions

Search one conversation's message history for matching messages.

Use this to find specific messages ("who mentioned pizza?", "what did Ada say last week?") instead of paging manually with read_messages. GroupMe has no search API, so this scans backwards from the newest message, matching query against message text and sender_name against sender names (both case-insensitive substrings), until limit matches are found, the oldest message is reached, or max_messages_scanned messages have been examined. The result reports exactly how far the scan got — check oldest_message_reached and note before concluding something was never said.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Stop after this many matches (1-100).
`query`	Yes	Text to look for in message text. May be empty only when ``sender_name`` is given (a sender-only search).
`sender_name`	No	Only match messages whose sender's display name contains this.
`conversation`	Yes	Which conversation to search: ``{"kind": "group", "group_id": ...}`` or ``{"kind": "direct", "other_user_id": ...}`` (ids from ``list_conversations``).
`response_format`	No	``"concise"`` (default) for sender names, text, relative ages, and like counts; ``"detailed"`` adds sender ids, conversation ids, and ISO timestamps.	concise
`max_messages_scanned`	No	Stop after examining this many messages (1-5000); a hit cap is reported in ``note``, never silent.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`note`	No
`count`	Yes
`matches`	Yes
`next_before_id`	No
`messages_scanned`	Yes
`oldest_message_reached`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Aug 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover safety (readOnly/idempotent/non-destructive/openWorld); the description adds substantial mechanics the annotations cannot: no native search API, backward scan from newest, case-insensitive substring matching, the three termination conditions, and the caveat to inspect oldest_message_reached and note before concluding a message was never sent. This is exactly the kind of result-interpretation context an agent needs.

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?

Front-loaded with purpose, then usage, then mechanics, in three tight paragraphs with no filler. Slightly dense and longer than strictly necessary, but nearly every clause carries operational information.

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?

Covers the full picture for a six-parameter search tool: what it does, when to prefer it, how matching and scanning terminate, and how to read the result fields. An output schema exists, so the description correctly stops short of enumerating return structure while still flagging the fields that change interpretation.

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 baseline is 3. The description goes beyond it by explaining that query matches message text and sender_name matches sender names, both as case-insensitive substrings, and by framing limit and max_messages_scanned as scan-stopping conditions rather than just numeric bounds.

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 (search), a bounded resource (one conversation's message history), and the match target, which cleanly separates it from read_messages and get_conversation_context. The scope word 'one conversation' prevents the agent from assuming a global search.

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 routes the agent: use this to find specific messages instead of paging manually with read_messages, backed by concrete example queries. The when-to-use condition and the alternative it replaces are both named.

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

Deploy Server