Search guild messages
discord_
Read-only
- Toolset
- Messages
messages - Discord permission
- Read Message History
- Context cost
- 615 tokens, estimated2,460 bytes of definition, divided by 4
Search for messages across all channels in a guild using Discord's native search API. Returns at most 25 messages matching the query with channel context, with no way to page past them. Age-restricted (NSFW) channels are left out. Requires the Read Message History permission and the Message Content privileged intent, enabled in the Developer Portal. While Discord is still building the server's search index, the call fails and says how many seconds to wait. Use discord_ for a substring scan of one channel's last 100 messages. To read the messages around a hit, use discord_ with around.
Risk and annotations
Read-onlyreadOnlyHint | yes | Does not modify your server. |
|---|---|---|
DestructivedestructiveHint | n/a | Not declared: it only applies to tools that write. |
IdempotentidempotentHint | n/a | Not declared. |
Open worldopenWorldHint | yes | Interacts with an external system: Discord. |
Annotations are hints the server declares. Clients use them to decide when to ask you before a call.
Parameters
| Parameter | Type | Rules | Description |
|---|---|---|---|
| guild_ | string | pattern ^\d{17,20}$ | Discord server (guild) ID (snowflake). |
| queryrequired | string | none | Search query (case-insensitive). |
| channel_ | string | pattern ^\d{17,20}$ | Optional. Restrict search to this channel ID. |
| author_ | string | pattern ^\d{17,20}$ | Optional. Only show messages from this user ID. |
| limitoptional | integer | 1 to 25default 25 | Max messages to return (1–25). Default 25. |
Output
Declared by outputSchema: clients receive this shape as structuredContent.
| Field | Type | Description |
|---|---|---|
| matchesrequired | array of objects | |
| id (nested, level 1)required | string | |
| author (nested, level 1)required | string | |
| author_ | string | |
| webhook_ | string | |
| content (nested, level 1)required | string | |
| timestamp (nested, level 1)required | string | |
| embeds (nested, level 1) | array of objects | |
| title (nested, level 2) | string | |
| author (nested, level 2) | string | |
| description (nested, level 2) | string | |
| url (nested, level 2) | string | |
| fields (nested, level 2) | array of objects | |
| name (nested, level 3)required | string | |
| value (nested, level 3)required | string | |
| moreFields (nested, level 2) | number | Count of fields left out past the first 10. Absent when none were. |
| footer (nested, level 2) | string | |
| channel_ | string | |
| channel_ | string |
Related tools
Named in its description
Also in Messages
-
Send message, Write
discord_send_ message -
Reply to message, Write
discord_reply_ message -
Edit message, Write
discord_edit_ message -
Add reaction, Write
discord_add_ reaction -
List channel threads, Read-only
discord_list_ channel_ threads -
Create thread, Write
discord_create_ thread -
Bulk delete messages, Destructive
discord_bulk_ delete_ messages -
Send embed, Write
discord_send_ embed -
Edit embed, Write
discord_edit_ embed -
Send multiple embeds, Write
discord_send_ multiple_ embeds -
Delete message, Destructive
discord_delete_ message -
Pin or unpin message, Write
discord_pin_ message -
Crosspost message, Write
discord_crosspost_ message -
Remove reactions, Destructive
discord_remove_ reactions -
Get reactions, Read-only
discord_get_ reactions -
Get message attachments, Read-only
discord_get_ message_ attachments -
Fetch pinned messages, Read-only
discord_fetch_ pinned_ messages -
Forward message, Write
discord_forward_ message
Raw definition (2,460 bytes)
{
"name": "discord_search_guild_messages",
"description": "Search for messages across all channels in a guild using Discord's native search API. Returns at most 25 messages matching the query with channel context, with no way to page past them. Age-restricted (NSFW) channels are left out. Requires the Read Message History permission and the Message Content privileged intent, enabled in the Developer Portal. While Discord is still building the server's search index, the call fails and says how many seconds to wait. Use discord_search_messages for a substring scan of one channel's last 100 messages. To read the messages around a hit, use discord_read_messages with around.",
"inputSchema": {
"type": "object",
"properties": {
"guild_id": {
"type": "string",
"pattern": "^\\d{17,20}$",
"description": "Discord server (guild) ID (snowflake)."
},
"query": {
"type": "string",
"description": "Search query (case-insensitive)."
},
"channel_id": {
"description": "Optional. Restrict search to this channel ID.",
"type": "string",
"pattern": "^\\d{17,20}$"
},
"author_id": {
"description": "Optional. Only show messages from this user ID.",
"type": "string",
"pattern": "^\\d{17,20}$"
},
"limit": {
"default": 25,
"description": "Max messages to return (1–25). Default 25.",
"type": "integer",
"minimum": 1,
"maximum": 25
}
},
"required": [
"guild_id",
"query"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"author": {
"type": "string"
},
"author_id": {
"type": "string"
},
"webhook_id": {
"type": "string"
},
"content": {
"type": "string"
},
"timestamp": {
"type": "string"
},
"embeds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"author": {
"type": "string"
},
"description": {
"type": "string"
},
"url": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"name",
"value"
],
"additionalProperties": false
}
},
"moreFields": {
"description": "Count of fields left out past the first 10. Absent when none were.",
"type": "number"
},
"footer": {
"type": "string"
}
},
"additionalProperties": false
}
},
"channel_id": {
"type": "string"
},
"channel_name": {
"type": "string"
}
},
"required": [
"id",
"author",
"author_id",
"content",
"timestamp",
"channel_id",
"channel_name"
],
"additionalProperties": false
}
}
},
"required": [
"matches"
],
"additionalProperties": false
},
"annotations": {
"title": "Search guild messages",
"readOnlyHint": true,
"openWorldHint": true
}
}