Skip to main content
Glama
googlarz

Signal MCP

by googlarz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

search_messages

Read-onlyIdempotent

Find messages by keyword, sender, or date range across local conversations. Results are returned newest first and support pagination.

Instructions

Full-text search of message bodies across all conversations in the local store (SQLite FTS; no Signal server call, nothing marked read). Only messages stored on this device are found. Use get_conversation to read a chat in order. query: words to find (all words must occur; falls back to substring match if FTS fails; empty returns []). sender: only messages from this E.164 number. since (inclusive) / until (exclusive) ISO dates, e.g. since=2024-01-01, until=2024-01-02 covers all of Jan 1; invalid dates return an error. limit: max results (default 50, clamped 1-500); offset: skip N results for paging (default 0). Returns a list of messages, newest first (id, sender, sender_name, recipient, group_id, group_name, body, timestamp, attachments …).

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum results to return (default 50, clamped 1-500)
queryYesKeyword or phrase to search for
sinceNoOnly messages at or after this ISO datetime (e.g. 2024-01-01 or 2024-01-01T09:00:00)
untilNoOnly messages strictly before this ISO datetime (exclusive; until=2024-01-02 includes all of Jan 1)
offsetNoSkip this many results for pagination (default 0)
senderNoFilter results to messages from this phone number (E.164)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.43.0
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum results to return (default 50)"New value: +"Maximum results to return (default 50, clamped 1-500)"
  2. Changed2 schema fields changedv1.39.0
    • addedInput schema / properties / since
      Added value: +{
+  "description": "Only messages at or after this ISO datetime (e.g. 2024-01-01 or 2024-01-01T09:00:00)",
+  "type": "string"
+}
    • addedInput schema / properties / until
      Added value: +{
+  "description": "Only messages strictly before this ISO datetime (exclusive; until=2024-01-02 includes all of Jan 1)",
+  "type": "string"
+}
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), but the description adds substantial behavioral context beyond them: no Signal server call, nothing marked read, only locally stored messages are found, FTS failure falls back to substring matching, and invalid dates return an error. These are non-obvious traits 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 capabilities then per-parameter notes in one dense paragraph; every clause carries information. It does duplicate some schema details (date examples, limit clamp), which keeps it just short of ideal.

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?

No output schema exists, yet the description enumerates the returned fields (id, sender, sender_name, recipient, group_id, group_name, body, timestamp, attachments) and ordering (newest first), plus pagination and error behavior. An agent has everything needed to call and interpret it.

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 the baseline is 3, but the description adds genuine meaning: multiple words must all occur (AND semantics not in the schema's 'keyword or phrase'), empty query returns [], and boundary examples for since/until. It repeats the limit clamping and date exclusivity already in the schema.

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 (full-text search) and resource (message bodies) with a precise scope: 'across all conversations in the local store'. It explicitly distinguishes itself from get_conversation for reading a chat in order, so an agent can route without opening either schema.

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?

Names the alternative ('Use get_conversation to read a chat in order') and defines the boundary conditions: local device only, no server call, nothing marked read. The when-to-use and when-not-to-use conditions are both explicit.

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

Deploy Server

Other Tools