Skip to main content
Glama
inboxd
by 47star

search_messages

Search a local read-only archive of messages, email, calendars, tasks, notes, and reminders by terms, dates, sender, or conversation to find matching records and previews.

Instructions

Search communication, calendars, tasks, notes, reminders and installed source records.

Use order='newest', limit=1 for the latest matching message, code or email. The default order is relevance. before/after are inclusive ISO 8601 timestamps with timezone offsets. match='all' requires all terms; match='any' matches alternate spellings and languages. Each term needs 2+ characters; double quotes group a phrase. sender is an exact source ID, not a display name. conversation_id limits one conversation. Returns previews with read_request; follow next_request for another page. Profile/channel metadata is excluded. Check context for collection and indexing gaps. Searches titles, bodies, source comments and extracted attachments. Work-item HTML is rendered as text. matched_fields identifies where terms occur; preview_field identifies the excerpt source. Relevance scores title, body, comments and attachments separately.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
afterNo
limitNo
matchNoall
orderNorelevance
queryYes
beforeNo
offsetNo
senderNo
sourceNo
conversation_idNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the return shape (previews with read_request), pagination via next_request, that profile/channel metadata is excluded, and that context must be checked for collection/indexing gaps. It also explains how matched_fields, preview_field and per-field relevance scoring behave. What is missing is any statement of authorization requirements or rate limits for a cross-source search.

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?

The purpose sentence is front-loaded and subsequent lines cover distinct topics (ordering, time filters, matching, scoping, returns, coverage) without repetition. Some sentences are wrapped awkwardly mid-clause ('conversation_id limits / one conversation') and the output-field notes could be tightened, but almost every line adds usable information.

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

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, no-annotation, no-output-schema search tool, the description covers query construction, filtering, ordering, pagination, and the meaning of returned fields such as matched_fields and preview_field. An agent could invoke it correctly and interpret results without additional documentation; only offset, source, and auth/rate-limit behavior remain unaddressed.

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 description coverage is 0%, so the description must compensate across 10 parameters, and it largely does: query syntax (2+ character terms, quoted phrases, match='all' vs 'any'), order defaults and semantics, inclusive ISO 8601 before/after, sender as an exact source ID rather than display name, and conversation_id. Only offset and the source parameter are left unexplained, which keeps it short of a 5.

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?

Opens with a specific verb ('Search') and enumerates the resource domain: communication, calendars, tasks, notes, reminders and installed source records. An agent knows exactly what corpus is being queried, though the description does not directly name which sibling (get_message, get_conversation, get_recent_records) to prefer for a single-record lookup.

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?

Gives one concrete usage pattern ('Use order=newest, limit=1 for the latest matching message') and a scoping hint ('conversation_id limits one conversation'), which is real guidance. It never states when not to use this tool or routes the agent to alternative siblings for fetching a specific message or thread, so the coverage is partial rather than complete.

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