Skip to main content
Glama
googlarz

Signal MCP

by googlarz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

get_unread

Check for new unread incoming Signal messages across all conversations; returned messages are marked read locally and an optional limit controls batch size.

Instructions

Return new unread incoming messages across all conversations — the default way to check for new messages. If the background service (signal-mcp install-service) is running it reads the local store; otherwise it first polls signal-cli (at most once per 30 s) and adds a _warning suggesting the service. Use get_conversation for a chat's full history, list_conversations for an inbox overview. limit: max messages (default 50, clamped 1-500); the newest are kept. Side effect: returned messages are marked read in the local store only (no read receipt — use send_read_receipt; mark_as_unread to undo). Returns {messages (oldest first; id, sender, sender_name, group_id, group_name, body, timestamp, attachments …), has_more}; if has_more is true call again with the same limit to get the next batch.

Input Schema

NameRequiredDescriptionDefault
limitNoMax messages to return (default: 50)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A5/5.0
Behavior5/5

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

Annotations already indicate the operation is not read-only, not destructive, not idempotent, and open-world. The description goes further by disclosing the local-store read-marking side effect, the absence of a read receipt, the background service behavior, and the at-most-once-per-30s polling fallback. This gives an agent unusually rich operational context.

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

Conciseness5/5

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

The description is dense but front-loaded, opening with the tool's primary purpose before detailing side effects, alternatives, parameter behavior, and pagination. Every sentence carries operational value, especially given the absence of an output schema.

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?

With no output schema, the description fully compensates by describing the return object shape, key fields, ordering, and has_more pagination. It also covers side effects, alternative tools, and the optional limit's behavior, leaving no critical invocation gap.

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

Parameters5/5

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

The single limit parameter is well covered by the schema, but the description adds important semantics missing there: the value is clamped to 1-500 and the newest messages are kept when more exist. That directly affects how an agent should invoke the tool and interpret results.

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?

The description states a specific verb and resource: returns new unread incoming messages across all conversations. It immediately distinguishes this tool as the default way to check for new messages, helping an agent separate it from sibling tools such as get_conversation and list_conversations.

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?

It explicitly says when to use this tool (default check for new messages) and names alternatives for related tasks: get_conversation for full chat history and list_conversations for an inbox overview. It also documents the side effect and points to send_read_receipt and mark_as_unread for receipt/undo behavior.

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