discord-mcp

discord_search_guild_messages

Read-onlyIdempotent

Search all Discord guild messages by full-text query and filters like author, channel, mentions, attachments, links, embeds, pinned state, or message ID range, with paginated newest-first results.

Instructions

Search messages across a whole guild by text and filters (author, channel, mentions, attachments, links, embeds, pinned state, message ID range). Use discord_list_messages to read one channel in order. Results come back newest first by default; a page can hold fewer than limit, so page with offset=next_offset until it is null. A new or busy guild index can answer "not ready"; the tool then fails with a retryable error that carries the retry delay in seconds. Results omit reactions. Bot permissions it may need: View Channel, Read Message History. Read-only; safe to retry.

Input Schema

Name	Required	Description
`has`	No	Filter by media attachment or item presence (e.g. 'link', 'embed', 'file', 'image', 'video', 'sound', 'sticker', 'poll') or negate with '-' (e.g. '-poll')
`slop`	No	Max words allowed between matching words of content (0-100, default 2)
`limit`	No	Max number of message results per page (1-25; default is 25)
`max_id`	No	Message snowflake ID ceiling (only messages created before this snowflake ID)
`min_id`	No	Message snowflake ID floor (only messages created after this snowflake ID)
`offset`	No	Paging offset index into search results (use next_offset to page forward)
`pinned`	No	Filter only pinned messages when true, or unpinned when false
`content`	No	Full-text query string to match inside message content
`sort_by`	No	Sort criterion for matching messages: 'timestamp' or 'relevance' (default 'timestamp')
`guild_id`	Yes	ID of the guild to search messages in
`mentions`	No	Only messages that mention these user IDs (up to 100)
`author_id`	No	Only messages from these user IDs (up to 100)
`channel_id`	No	Filter messages within specific channel or thread IDs (up to 500)
`embed_type`	No	Filter messages containing specific embed types: 'image', 'video', 'gif', 'sound', 'article'
`sort_order`	No	Sort direction, 'asc' or 'desc' (default 'desc'). Ignored when sort_by is 'relevance'
`author_type`	No	Filter by author type: 'user', 'bot', 'webhook', or negated with '-' prefix (e.g. '-bot')
`include_nsfw`	No	Whether to include results from age-restricted (NSFW) channels (default false)
`link_hostname`	No	Only messages containing links to these domains (up to 100)
`embed_provider`	No	Only messages with an embed from these providers, case-sensitive, for example 'Tenor' (up to 100)
`mention_everyone`	No	Filter whether the message mentions @everyone or @here
`mentions_role_id`	No	Only messages that mention these role IDs (up to 100)
`replied_to_user_id`	No	Only messages sent in reply to these user IDs (up to 100)
`attachment_filename`	No	Only messages with an attachment with one of these filenames (up to 100)
`attachment_extension`	No	Filter messages by file extension on attachments (e.g. 'png', 'pdf'; up to 100)
`replied_to_message_id`	No	Only messages replying directly to these message IDs (up to 100)

Output Schema

Name	Required	Description	Default
`members`	No
`threads`	No
`messages`	Yes
`next_offset`	Yes
`total_results`	Yes
`documents_indexed`	No
`doing_deep_historical_index`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed44 schema fields changedv0.1.2Nov 4, 2026

addedInput schema / properties / attachment_extension / description

Added value: +"Filter messages by file extension on attachments (e.g. 'png', 'pdf'; up to 100)"

addedInput schema / properties / attachment_filename / description

Added value: +"Only messages with an attachment with one of these filenames (up to 100)"

addedInput schema / properties / author_id / description

Added value: +"Only messages from these user IDs (up to 100)"

addedInput schema / properties / author_id / items / description
```
Added value: +"Author snowflake ID"
```

addedInput schema / properties / author_type / description

Added value: +"Filter by author type: 'user', 'bot', 'webhook', or negated with '-' prefix (e.g. '-bot')"

addedInput schema / properties / channel_id / description

Added value: +"Filter messages within specific channel or thread IDs (up to 500)"

addedInput schema / properties / channel_id / items / description
```
Added value: +"Channel snowflake ID to limit search within"
```

addedInput schema / properties / content / description

Added value: +"Full-text query string to match inside message content"

addedInput schema / properties / embed_provider / description

Added value: +"Only messages with an embed from these providers, case-sensitive, for example 'Tenor' (up to 100)"

addedInput schema / properties / embed_type / description

Added value: +"Filter messages containing specific embed types: 'image', 'video', 'gif', 'sound', 'article'"

addedInput schema / properties / guild_id / description

Added value: +"ID of the guild to search messages in"

addedInput schema / properties / has / description

Added value: +"Filter by media attachment or item presence (e.g. 'link', 'embed', 'file', 'image', 'video', 'sound', 'sticker', 'poll') or negate with '-' (e.g. '-poll')"

addedInput schema / properties / include_nsfw / description

Added value: +"Whether to include results from age-restricted (NSFW) channels (default false)"

addedInput schema / properties / limit / description

Added value: +"Max number of message results per page (1-25; default is 25)"

addedInput schema / properties / link_hostname / description

Added value: +"Only messages containing links to these domains (up to 100)"

addedInput schema / properties / max_id / description

Added value: +"Message snowflake ID ceiling (only messages created before this snowflake ID)"

addedInput schema / properties / mention_everyone / description

Added value: +"Filter whether the message mentions @everyone or @here"

addedInput schema / properties / mentions / description

Added value: +"Only messages that mention these user IDs (up to 100)"

addedInput schema / properties / mentions / items / description
```
Added value: +"Mentioned user snowflake ID"
```

addedInput schema / properties / mentions_role_id / description

Added value: +"Only messages that mention these role IDs (up to 100)"

addedInput schema / properties / mentions_role_id / items / description
```
Added value: +"Mentioned role snowflake ID"
```

addedInput schema / properties / min_id / description

Added value: +"Message snowflake ID floor (only messages created after this snowflake ID)"

addedInput schema / properties / offset / description

Added value: +"Paging offset index into search results (use next_offset to page forward)"

addedInput schema / properties / pinned / description

Added value: +"Filter only pinned messages when true, or unpinned when false"

addedInput schema / properties / replied_to_message_id / description

Added value: +"Only messages replying directly to these message IDs (up to 100)"

addedInput schema / properties / replied_to_message_id / items / description
```
Added value: +"Replied-to message snowflake ID"
```

addedInput schema / properties / replied_to_user_id / description

Added value: +"Only messages sent in reply to these user IDs (up to 100)"

addedInput schema / properties / replied_to_user_id / items / description
```
Added value: +"Replied-to user snowflake ID"
```

addedInput schema / properties / slop / description

Added value: +"Max words allowed between matching words of content (0-100, default 2)"

addedInput schema / properties / sort_by / description

Added value: +"Sort criterion for matching messages: 'timestamp' or 'relevance' (default 'timestamp')"

addedInput schema / properties / sort_order / description

Added value: +"Sort direction, 'asc' or 'desc' (default 'desc'). Ignored when sort_by is 'relevance'"

changedOutput schema / properties / members / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": {},
-      "properties": {
-        "flags": {
-          "type": "number"
-        },
-        "id": {
-          "pattern": "^\\d+$",
-          "type": "string"
-        },
-        "join_timestamp": {
-          "type": "string"
-        },
-        "member": {
-          "additionalProperties": {},
-          "properties": {
-            "joined_at": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "nick": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "roles": {
-              "items": {
-                "pattern": "^\\d+$",
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "user": {
-              "additionalProperties": {},
-              "properties": {
-                "bot": {
-                  "type": "boolean"
-                },
-                "global_name": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                },
-                "id": {
-                  "pattern": "^\\d+$",
-                  "type": "string"
-                },
-                "username": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "id"
-              ],
-              "type": "object"
-            }
-          },
-          "type": "object"
-        },
-        "user_id": {
-          "pattern": "^\\d+$",
-          "type": "string"
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": {},
+      "properties": {
+        "flags": {
+          "type": "number"
+        },
+        "id": {
+          "description": "Discord snowflake ID as a numeric string",
+          "pattern": "^\\d+$",
+          "type": "string"
+        },
+        "join_timestamp": {
+          "type": "string"
+        },
+        "member": {
+          "additionalProperties": {},
+          "properties": {
+            "joined_at": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "nick": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "roles": {
+              "items": {
+                "description": "Discord snowflake ID as a numeric string",
+                "pattern": "^\\d+$",
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "user": {
+              "additionalProperties": {},
+              "properties": {
+                "bot": {
+                  "type": "boolean"
+                },
+                "global_name": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "id": {
+                  "description": "Discord snowflake ID as a numeric string",
+                  "pattern": "^\\d+$",
+                  "type": "string"
+                },
+                "username": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id"
+              ],
+              "type": "object"
+            }
+          },
+          "type": "object"
+        },
+        "user_id": {
+          "description": "Discord snowflake ID as a numeric string",
+          "pattern": "^\\d+$",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / messages / items / items / properties / attachments / items / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
removedOutput schema / properties / messages / items / items / properties / author / properties / global_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / messages / items / items / properties / author / properties / global_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
addedOutput schema / properties / messages / items / items / properties / author / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
addedOutput schema / properties / messages / items / items / properties / channel_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
removedOutput schema / properties / messages / items / items / properties / edited_timestamp / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / messages / items / items / properties / edited_timestamp / type
```
Added value: +[
+  "string",
+  "null"
+]
```
addedOutput schema / properties / messages / items / items / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
addedOutput schema / properties / messages / items / items / properties / message_reference / properties / channel_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
addedOutput schema / properties / messages / items / items / properties / message_reference / properties / guild_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
addedOutput schema / properties / messages / items / items / properties / message_reference / properties / message_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```

changedOutput schema / properties / threads / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": {},
-      "properties": {
-        "guild_id": {
-          "pattern": "^\\d+$",
-          "type": "string"
-        },
-        "id": {
-          "pattern": "^\\d+$",
-          "type": "string"
-        },
-        "name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "parent_id": {
-          "anyOf": [
-            {
-              "pattern": "^\\d+$",
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "position": {
-          "type": "number"
-        },
-        "topic": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "type": {
-          "type": "number"
-        }
-      },
-      "required": [
-        "id"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": {},
+      "properties": {
+        "guild_id": {
+          "description": "Discord snowflake ID as a numeric string",
+          "pattern": "^\\d+$",
+          "type": "string"
+        },
+        "id": {
+          "description": "Discord snowflake ID as a numeric string",
+          "pattern": "^\\d+$",
+          "type": "string"
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "parent_id": {
+          "anyOf": [
+            {
+              "description": "Discord snowflake ID as a numeric string",
+              "pattern": "^\\d+$",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "position": {
+          "type": "number"
+        },
+        "topic": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

First observedv0.1.0Nov 3, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond the annotations (readOnly, idempotent, openWorld, non-destructive) by disclosing default ordering (newest first), that a page may return fewer than limit, the specific retryable cold-index failure with its retry delay in seconds, that reactions are omitted from results, and which bot permissions are required. These are the non-obvious traits that would otherwise cause mis-invocation or incorrect retry logic.

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?

Four sentences, front-loaded with purpose then alternative then pagination then failure modes; no sentence is filler and each one changes agent behavior. Dense but appropriately so for a 25-parameter tool.

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?

For a complex search tool with a full input schema and an output schema, the remaining description burden is exactly pagination, failure/retry behavior, and result caveats — all of which are covered. Nothing an agent needs to call it safely and correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 25 parameters, so the schema already carries the per-parameter meaning and the description need only avoid contradicting it. The description's parenthetical filter list helps an agent recognize what is filterable, but it adds no syntax, precedence, or interaction rules (e.g. how min_id/max_id combine with sort_by) beyond the schema, so it sits at the baseline.

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?

Opens with a specific verb and resource — search messages across a whole guild — and enumerates the filter families (author, channel, mentions, attachments, links, embeds, pinned state, ID range) that define scope. It explicitly contrasts with discord_list_messages, so an agent can separate guild-wide search from single-channel reading without opening either schema.

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?

Names the alternative tool and the condition that selects it ('Use discord_list_messages to read one channel in order'), which is the exact when-to-use split an agent needs. It also gives operational guidance for the awkward cases: paging with offset=next_offset until null, and handling the retryable 'not ready' index error.

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