search_messages

Search messages using Discord’s native search engine. Supports all Discord search filters: content text, author, channel, mentions, attachment type (link/embed/file/video/image/sound/sticker), pinned status, author type (user/bot/webhook), and date ranges via snowflake IDs. Use for narrow, specific searches. Results are paginated (max 25 per page) — use the ‘before’ parameter with the last message ID to get the next page. Returned messages are sorted chronologically (oldest first) within each page.

User guide / All capabilities

Contract

Effect: read. Evidence role: message_evidence.

Search guild messages via Discord’s native search. Exposes all Discord search filters: content, author_id, channel_id, mentions, has (link/embed/file/video/image/sound/sticker), pinned, author_type (user/bot/webhook), date bounds via snowflake IDs. Use for precise, filtered searches that retrieve_messages can’t handle efficiently.

Parameters

This is the current provider-facing JSON Schema, generated from the runtime definition.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Text content to search for. Works like Discord's search bar."
    },
    "author_id": {
      "type": "string",
      "description": "Filter to messages from this user ID. Resolve the user first with resolve_member_identity."
    },
    "channel_id": {
      "type": "string",
      "description": "Filter to messages in this channel ID."
    },
    "mentions": {
      "type": "string",
      "description": "Filter to messages that mention this user ID."
    },
    "has": {
      "type": "string",
      "description": "Filter by attachment type. Valid values: link, embed, file, video, image, sound, sticker."
    },
    "pinned": {
      "type": "string",
      "description": "Filter by pinned status. Valid values: true, false."
    },
    "author_type": {
      "type": "string",
      "description": "Filter by author type. Valid values: user, bot, webhook."
    },
    "before": {
      "type": "string",
      "description": "Only messages before this snowflake ID. Use for pagination: pass the ID of the last message from the previous page."
    },
    "after": {
      "type": "string",
      "description": "Only messages after this snowflake ID."
    },
    "sort_by": {
      "type": "string",
      "description": "Sort results. Valid values: timestamp, relevance. Default: relevance."
    },
    "sort_order": {
      "type": "string",
      "description": "Sort direction. Valid values: asc, desc. Default: desc."
    },
    "offset": {
      "type": "number",
      "description": "Numeric offset for pagination (max 5000). Prefer using before/after snowflake IDs for large result sets."
    },
    "limit": {
      "type": "number",
      "description": "Number of results per page (max 25, default 25)."
    }
  },
  "required": []
}

Execution requirements

• guild context must exist

Expected postconditions

• returns Discord search results as message evidence