retrieve_messages

Search Discord message history. Returns messages with full metadata including message IDs, author IDs, channel IDs, timestamps, and jump links. Use ‘mode’ to control retrieval: ‘history’ for chronological scrolling (like reading a file), ‘semantic’ for relevance-based search, ‘mixed’ for both. Use ‘cursor’ from previous results to paginate through more messages. Use ‘aroundMessageId’ to get context surrounding a specific message ID.

User guide / All capabilities

Contract

Effect: read. Evidence role: message_evidence.

Read scoped Discord channel history first, add semantic matches from the same scope, and continue with live history fetches when needed.

Parameters

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

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query for Discord messages. Used for both lexical and semantic matching."
    },
    "channelIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Limit search to these channel IDs (from resolve_channel_targets or list_guild_structure). Omit to search all indexed channels."
    },
    "authorId": {
      "type": "string",
      "description": "Filter messages to this author's Discord snowflake ID (from resolve_member_identity)."
    },
    "beforeTimestamp": {
      "type": "number",
      "description": "Unix timestamp (ms). Only return messages before this time. When computing a year for a partial date (day+month only): if that day/month has already passed relative to `current_date`, use the current year; if it is still upcoming, use the previous year."
    },
    "afterTimestamp": {
      "type": "number",
      "description": "Unix timestamp (ms). Only return messages after this time. When computing a year for a partial date (day+month only): if that day/month has already passed relative to `current_date`, use the current year; if it is still upcoming, use the previous year."
    },
    "aroundMessageId": {
      "type": "string",
      "description": "A Discord message ID from previous results. Returns messages surrounding that message for reading context. Use this to zoom into a specific conversation point."
    },
    "mode": {
      "type": "string",
      "enum": [
        "history",
        "semantic",
        "mixed"
      ],
      "description": "Retrieval mode. 'history' = chronological order (best for reading through a channel like a file). 'semantic' = relevance-ranked search. 'mixed' = both lanes. Default: mixed."
    },
    "order": {
      "type": "string",
      "enum": [
        "newest",
        "oldest"
      ],
      "description": "Chronological direction for history mode. 'newest' (default) returns most recent first. 'oldest' returns messages from the start of the channel forward — useful for answering 'what did people say in the beginning?'. When the channel has not been fully indexed yet, results include a `partialIndex` block and a background crawl is triggered so you can keep calling retrieve_messages to progress through older history."
    },
    "fromDate": {
      "type": "string",
      "description": "ISO8601 date/timestamp or numeric Unix ms. Anchor for chronological reads. With order='oldest', returns messages at or after this date. With order='newest', returns messages at or before this date. Equivalent to setting afterTimestamp (oldest) or beforeTimestamp (newest) but accepts human-readable dates."
    },
    "limit": {
      "type": "number",
      "description": "Number of messages to return per page. Omit to use server default. Match the user's requested count when they ask for a specific number."
    },
    "cursor": {
      "type": "object",
      "description": "Continuation cursor from a previous retrieve_messages call. Pass this exactly as received to fetch the next page and keep scrolling through history.",
      "properties": {
        "history": {
          "type": "object",
          "description": "History pagination state. Pass through as-is from previous results.",
          "properties": {},
          "required": []
        },
        "semantic": {
          "type": "object",
          "properties": {
            "lastScore": {
              "type": "number"
            },
            "lastCreatedTimestamp": {
              "type": "number"
            },
            "lastMessageId": {
              "type": "string"
            }
          },
          "required": []
        }
      },
      "required": []
    },
    "excludedMessageIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Message IDs to exclude from results (already seen in previous pages)."
    }
  },
  "required": [
    "query"
  ]
}

Execution requirements

• guild context should exist for live escalation

Expected postconditions

• returns message evidence from the local cache after any needed live fetch