Skip to main content
Glama
owlpost

owlpost

search_messages

Read-onlyIdempotent

Search a mail folder using filters for sender, recipient, subject, body, date, read status, flags, and attachments, returning message envelopes newest first without marking messages as read.

Instructions

Search one folder with structured filters and return message envelopes, newest first.

All filters are combined with AND. String filters use IMAP case-insensitive substring matching; multi-word values are quoted for you. Each result has uid, folder, message_id, subject, from/to/cc, date, flags, size, seen and flagged; pass folder + uid to read_email for the body. The folder is opened read-only, so searching never marks mail read.

Args: account: Account name from list_accounts. folder: Folder to search (default "INBOX"); use list_folders or resolve_folder for others. from_: Substring of the From header (name or address). to: Substring of the To header. cc: Substring of the Cc header. subject: Substring of the Subject. body: Substring of the message body. text: Substring of headers or body. since: Only messages on or after this date (YYYY-MM-DD). before: Only messages before this date (YYYY-MM-DD). unseen: Only unread messages. seen: Only read messages. flagged: Only flagged/starred messages. has_attachment: Best-effort filter for messages with attachments (multipart/mixed or an attachment disposition header). raw: A raw IMAP SEARCH string, e.g. 'OR FROM "alice" FROM "bob"'. When set, every other filter is ignored. limit: Maximum number of results (default 50).

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": {
      "account": "<account>"
    },
    "name": "search_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
ccNo
toNo
rawNo
bodyNo
seenNo
textNo
from_No
limitNo
sinceNo
beforeNo
folderNoINBOX
unseenNo
accountYes
flaggedNo
subjectNo
has_attachmentNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.3.0
    • addedOutput schema / $defs
      Added value: +{
      +  "Address": {
      +    "properties": {
      +      "email": {
      +        "title": "Email",
      +        "type": "string"
      +      },
      +      "name": {
      +        "title": "Name",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "name",
      +      "email"
      +    ],
      +    "title": "Address",
      +    "type": "object"
      +  },
      +  "Envelope": {
      +    "properties": {
      +      "bcc": {
      +        "items": {
      +          "$ref": "#/$defs/Address"
      +        },
      +        "title": "Bcc",
      +        "type": "array"
      +      },
      +      "cc": {
      +        "items": {
      +          "$ref": "#/$defs/Address"
      +        },
      +        "title": "Cc",
      +        "type": "array"
      +      },
      +      "date": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Date"
      +      },
      +      "date_iso": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Date Iso"
      +      },
      +      "flagged": {
      +        "title": "Flagged",
      +        "type": "boolean"
      +      },
      +      "flags": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Flags",
      +        "type": "array"
      +      },
      +      "folder": {
      +        "title": "Folder",
      +        "type": "string"
      +      },
      +      "from": {
      +        "items": {
      +          "$ref": "#/$defs/Address"
      +        },
      +        "title": "From",
      +        "type": "array"
      +      },
      +      "in_reply_to": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "In Reply To"
      +      },
      +      "message_id": {
      +        "title": "Message Id",
      +        "type": "string"
      +      },
      +      "references": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "References",
      +        "type": "array"
      +      },
      +      "seen": {
      +        "title": "Seen",
      +        "type": "boolean"
      +      },
      +      "size": {
      +        "anyOf": [
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Size"
      +      },
      +      "subject": {
      +        "title": "Subject",
      +        "type": "string"
      +      },
      +      "to": {
      +        "items": {
      +          "$ref": "#/$defs/Address"
      +        },
      +        "title": "To",
      +        "type": "array"
      +      },
      +      "uid": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Uid"
      +      }
      +    },
      +    "required": [
      +      "uid",
      +      "folder",
      +      "message_id",
      +      "in_reply_to",
      +      "references",
      +      "subject",
      +      "from",
      +      "to",
      +      "cc",
      +      "bcc",
      +      "date",
      +      "date_iso",
      +      "flags",
      +      "seen",
      +      "flagged",
      +      "size"
      +    ],
      +    "title": "Envelope",
      +    "type": "object"
      +  }
      +}
    • addedOutput schema / properties / result / items / $ref
      Added value: +"#/$defs/Envelope"
    • removedOutput schema / properties / result / items / additionalProperties
      Removed value: -true
    • removedOutput schema / properties / result / items / type
      Removed value: -"object"
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses the key operational behavior: the folder is opened read-only so searching never marks mail read — a real risk with IMAP SEARCH. It also explains filter composition (all AND), string matching semantics (case-insensitive substring, auto-quoting of multi-word values), ordering (newest first), and that has_attachment is best-effort rather than exact.

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 summary sentence is front-loaded and the Args block is scannable, which is appropriate for 16 parameters. A few lines are near-redundant with the parameter names (cc, to, subject), but the overall size is justified by the parameter count.

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?

An output schema exists, so the result-field enumeration is belt-and-braces but useful for deciding whether a follow-up read_email is needed. The definition covers all filters, matching semantics, and read-only safety for a 16-parameter tool; the only remaining gap is pagination/truncation semantics for limit and any error behavior for invalid folders or malformed raw queries.

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 carry all 16 parameters, and it does document each one with defaults and meaning, plus value-format details the schema omits (YYYY-MM-DD for since/before, raw IMAP syntax example, quoting behavior). It does not clarify whether seen/unseen are mutually exclusive or how they interact, and limit has no note about truncation behavior.

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 opening sentence gives a specific verb (search), a scoped resource (one folder), the mechanism (structured filters), and the return shape (message envelopes, newest first). The single-folder scope plus the redirect to read_email for bodies clearly separates it from siblings like read_email and get_conversation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It routes explicitly: use list_accounts for the account name, list_folders or resolve_folder for other folders, and pass folder + uid to read_email when the body is needed. It also states that setting raw disables every other filter, which prevents misuse. It lacks explicit guidance on when to prefer this over get_conversation for thread-shaped questions.

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