Read messages
discord_
Read-only
- Toolset
- Messages
messages - Discord permissions
- View Channel and Read Message History
- Context cost
- 981 tokens, estimated3,923 bytes of definition, divided by 4
Read messages from a text channel or thread, oldest-to-newest. Page backwards by re-calling with before set to the id of the oldest message you received, which walks a channel past the 100-message per-call cap. Requires the View Channel and Read Message History permissions; without Read Message History an empty result fails with an error naming the permission. Returns { messages: [...] } with id, author, content, timestamp, attachment count, pinned flag, and the text of any embeds. Use discord_ or discord_ to filter by keyword, or discord_ for pinned messages only.
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 |
|---|---|---|---|
| channel_ | string | pattern ^\d{17,20}$ | ID (snowflake) of the channel or thread to read from. |
| limitoptional | integer | 1 to 100default 20 | How many messages to fetch per call (1–100). Default 20. |
| beforeoptional | string | pattern ^\d{17,20}$ | Return only messages older than this message ID (snowflake). Page backwards through history by passing the id of the oldest message from the previous call. |
| afteroptional | string | pattern ^\d{17,20}$ | Return only messages newer than this message ID (snowflake). Page forwards by passing the id of the newest message from the previous call. |
| aroundoptional | string | pattern ^\d{17,20}$ | Return messages centered on this message ID (snowflake): Discord splits `limit` either side of it, and an even `limit` puts the extra message on the newer side. Use it to read outward from a known message, such as a discord_search_guild_messages hit. |
| sinceoptional | string | string:format datepattern (203 characters)^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$string:format date-timepattern (288 characters)^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ | Return only messages posted after this instant, as an ISO 8601 date or a date-time with an explicit offset (e.g. "2026-08-01" or "2026-08-01T09:00:00Z"). Convenience form of `after`: the call yields the oldest `limit` messages after that instant, so page forwards with `after` set to the newest id received. |
Output
Declared by outputSchema: clients receive this shape as structuredContent.
| Field | Type | Description |
|---|---|---|
| guild_ | string or null | |
| messagesrequired | 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 | |
| attachments (nested, level 1)required | number | |
| pinned (nested, level 1)required | boolean |
Related tools
Named in its description
-
Search messages, Read-only
discord_search_ messages -
Search guild messages, Read-only
discord_search_ guild_ messages -
Fetch pinned messages, Read-only
discord_fetch_ pinned_ messages
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 -
Forward message, Write
discord_forward_ message
Raw definition (3,923 bytes)
{
"name": "discord_read_messages",
"description": "Read messages from a text channel or thread, oldest-to-newest. Page backwards by re-calling with before set to the id of the oldest message you received, which walks a channel past the 100-message per-call cap. Requires the View Channel and Read Message History permissions; without Read Message History an empty result fails with an error naming the permission. Returns { messages: [...] } with id, author, content, timestamp, attachment count, pinned flag, and the text of any embeds. Use discord_search_messages or discord_search_guild_messages to filter by keyword, or discord_fetch_pinned_messages for pinned messages only.",
"inputSchema": {
"type": "object",
"properties": {
"channel_id": {
"type": "string",
"pattern": "^\\d{17,20}$",
"description": "ID (snowflake) of the channel or thread to read from."
},
"limit": {
"default": 20,
"description": "How many messages to fetch per call (1–100). Default 20.",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"before": {
"type": "string",
"pattern": "^\\d{17,20}$",
"description": "Return only messages older than this message ID (snowflake). Page backwards through history by passing the id of the oldest message from the previous call."
},
"after": {
"type": "string",
"pattern": "^\\d{17,20}$",
"description": "Return only messages newer than this message ID (snowflake). Page forwards by passing the id of the newest message from the previous call."
},
"around": {
"type": "string",
"pattern": "^\\d{17,20}$",
"description": "Return messages centered on this message ID (snowflake): Discord splits `limit` either side of it, and an even `limit` puts the extra message on the newer side. Use it to read outward from a known message, such as a discord_search_guild_messages hit."
},
"since": {
"anyOf": [
{
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
],
"description": "Return only messages posted after this instant, as an ISO 8601 date or a date-time with an explicit offset (e.g. \"2026-08-01\" or \"2026-08-01T09:00:00Z\"). Convenience form of `after`: the call yields the oldest `limit` messages after that instant, so page forwards with `after` set to the newest id received."
}
},
"required": [
"channel_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"guild_id": {
"type": [
"string",
"null"
]
},
"messages": {
"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
}
},
"attachments": {
"type": "number"
},
"pinned": {
"type": "boolean"
}
},
"required": [
"id",
"author",
"author_id",
"content",
"timestamp",
"attachments",
"pinned"
],
"additionalProperties": false
}
}
},
"required": [
"guild_id",
"messages"
],
"additionalProperties": false
},
"annotations": {
"title": "Read messages",
"readOnlyHint": true,
"openWorldHint": true
}
}