Skip to main content
Glama
plumbkit

plumb

Official
by plumbkit
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

check_messages

Read messages other agents have sent you, or block briefly to wait for a new one. Also lists your own undelivered sent mail without consuming it.

Instructions

Read messages other agents have sent you, optionally waiting for one to arrive. Receive half of plumb's mailbox; leave_note is the send half. Full etiquette — addressing, delivery, the exchange cap, cross-project rules: the plumb-chat skill.

Omit wait_seconds (or 0) to return immediately with whatever is waiting. A positive wait_seconds BLOCKS until a message arrives or the wait expires — hand your turn to a peer instead of polling. Capped by [collab] max_wait_seconds, kept below the client's own call timeout.

Each message is handed over exactly ONCE, by this tool or session_start; re-calling will not redeliver it. The block on other tool results only PREVIEWS a message — it marks nothing read, so a client that hides it loses nothing. Every message carries a conversation_id; quote it in leave_note to reply in thread.

Also reports your OWN unread mail — anything you sent that nobody has taken delivery of yet, with its age. Listing is a read; it never consumes the message on the recipient's behalf.

Requires [collab] mailbox = true.

Parameters: wait_seconds — block up to this long for a message (default 0, no wait).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
wait_secondsNoBlock up to this many seconds waiting for a message. 0 (default) returns immediately. Capped by [collab] max_wait_seconds.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.16.6

TDQS

A5/5.0
Behavior5/5

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

With no annotations present, the description carries full burden and excels: it discloses that each message is delivered exactly once, that previews do not mark as read, that the tool reports own unread mail without consuming, and the cap on wait_seconds. No contradictions with annotations (none provided).

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?

Each sentence delivers a distinct, valuable fact: purpose, wait behavior, delivery semantics, unread mail reporting, and prerequisite. The structure front-loads the core purpose and logically progresses to nuances, with no filler.

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?

The tool is complex (messaging, waiting, delivery semantics, unread mail) and has no output schema, yet the description covers all essential aspects for correct invocation: how messages are delivered, how to reply (quote conversation_id), the blocking behavior, the read-only nature of listing, and the required configuration. It also points to the plumb-chat skill for deeper etiquette, making it fully sufficient for an agent to use correctly.

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 description adds substantial meaning beyond the schema: it explains the blocking vs. immediate behavior of wait_seconds, the hand-off-to-peer pattern, and the cap by max_wait_seconds. Even though schema coverage is 100%, the description enriches understanding of the parameter's operational effect.

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 opens with a precise verb and resource: 'Read messages other agents have sent you.' It immediately differentiates itself from its send counterpart by explicitly naming leave_note as the send half, and mentions the mailbox scope ('Receive half of plumb's mailbox'), making its role unambiguous among siblings.

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?

Provides explicit guidance on when to use wait_seconds vs. not (omit or 0 for immediate return, positive blocks and hands turn to peer). It also states a prerequisite ('Requires [collab] mailbox = true') and directs to the plumb-chat skill for full etiquette, covering when-to-use and operational context.

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