discord-mcp

discord_edit_message

Destructive

Updates a bot-sent Discord message by replacing its text or embeds, adding files, and changing attached file descriptions or spoiler flags.

Instructions

Edit a message the bot sent: replace its content or embeds, add uploaded files, and change the description or spoiler flag of existing attachments. Existing attachments are always kept; they cannot be removed with this tool. Discord only lets a bot edit its own messages; to post a new message use discord_send_message. Returns the updated message. Bot permissions it may need: View Channel, Read Message History, Attach Files, Embed Links. Changes or removes existing Discord data without an approval prompt.

Input Schema

Name	Required	Description
`embeds`	No	Up to 10 rich embed objects; text across all embeds is limited to 6000 characters. Each object takes Discord embed fields such as title, description, url, color (integer), fields, author, footer, image and thumbnail
`content`	No	Message text, up to 2000 characters
`add_files`	No	New local files to upload and append to the message's existing attachments
`channel_id`	Yes	ID of the channel or thread that holds the message
`message_id`	Yes	ID of the message
`allowed_mentions`	No	Allowed mentions object controlling which role, user, or @everyone pings produce notifications; defaults to no pings
`update_attachments`	No	Changes to existing attachments, matched by attachment ID. Attachments not listed stay unchanged, and none are removed.

Output Schema

Name	Required	Description	Default
`message`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed35 schema fields changedv0.1.2Nov 4, 2026
- addedInput schema / properties / add_files / description
```
Added value: +"New local files to upload and append to the message's existing attachments"
```
- addedInput schema / properties / add_files / items / description
```
Added value: +"Local file upload specification with path and optional metadata"
```
- addedInput schema / properties / add_files / items / properties / content_type / description
```
Added value: +"MIME type of the file; detected from the file content when omitted"
```
- addedInput schema / properties / add_files / items / properties / description / description
```
Added value: +"Accessibility alt-text description for the attachment (up to 1024 characters)"
```
- addedInput schema / properties / add_files / items / properties / filename / description
```
Added value: +"Override filename sent to Discord; defaults to the basename of path"
```
- addedInput schema / properties / add_files / items / properties / is_spoiler / description
```
Added value: +"Whether to mark the attachment as a spoiler; defaults to false"
```
- addedInput schema / properties / add_files / items / properties / title / description
```
Added value: +"Display title for the uploaded file"
```
- addedInput schema / properties / allowed_mentions / description
```
Added value: +"Allowed mentions object controlling which role, user, or @everyone pings produce notifications; defaults to no pings"
```
- addedInput schema / properties / allowed_mentions / properties / parse / description
```
Added value: +"Allowed mention types to parse from message text: 'roles', 'users', or 'everyone'"
```
- addedInput schema / properties / allowed_mentions / properties / replied_user / description
```
Added value: +"Whether to mention the author of the message being replied to; defaults to false"
```
- addedInput schema / properties / allowed_mentions / properties / roles / description
```
Added value: +"Array of role IDs that can be mentioned in message content (up to 100)"
```
- addedInput schema / properties / allowed_mentions / properties / roles / items / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedInput schema / properties / allowed_mentions / properties / users / description
```
Added value: +"Array of user IDs that can be mentioned in message content (up to 100)"
```
- addedInput schema / properties / allowed_mentions / properties / users / items / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedInput schema / properties / channel_id / description
```
Added value: +"ID of the channel or thread that holds the message"
```
- addedInput schema / properties / content / description
```
Added value: +"Message text, up to 2000 characters"
```
- addedInput schema / properties / embeds / description
```
Added value: +"Up to 10 rich embed objects; text across all embeds is limited to 6000 characters. Each object takes Discord embed fields such as title, description, url, color (integer), fields, author, footer, image and thumbnail"
```
- addedInput schema / properties / embeds / items / description
```
Added value: +"One Discord embed object"
```
- addedInput schema / properties / message_id / description
```
Added value: +"ID of the message"
```
- addedInput schema / properties / update_attachments / description
```
Added value: +"Changes to existing attachments, matched by attachment ID. Attachments not listed stay unchanged, and none are removed."
```
- addedInput schema / properties / update_attachments / items / description
```
Added value: +"Attachment update descriptor for keeping, redescribing, or marking attachments as spoilers"
```
- addedInput schema / properties / update_attachments / items / properties / description / description
```
Added value: +"Updated alt-text description for the attachment (up to 1024 characters); omit to leave unchanged"
```
- addedInput schema / properties / update_attachments / items / properties / id / description
```
Added value: +"ID of the existing message attachment to retain or modify"
```
- addedInput schema / properties / update_attachments / items / properties / is_spoiler / description
```
Added value: +"Whether to mark or unmark the existing attachment as a spoiler; defaults to unchanged"
```
- addedOutput schema / properties / message / properties / attachments / items / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- removedOutput schema / properties / message / properties / author / properties / global_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / message / properties / author / properties / global_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- addedOutput schema / properties / message / properties / author / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedOutput schema / properties / message / properties / channel_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- removedOutput schema / properties / message / properties / edited_timestamp / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / message / properties / edited_timestamp / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- addedOutput schema / properties / message / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedOutput schema / properties / message / properties / message_reference / properties / channel_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedOutput schema / properties / message / properties / message_reference / properties / guild_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedOutput schema / properties / message / properties / message_reference / properties / message_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
First observedv0.1.0Nov 3, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is partly covered. The description still adds real context beyond them: the retained-attachment invariant, the specific bot permissions this call may require, and the no-approval-prompt warning. It stops short of covering failure modes such as editing a message authored by another user.

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?

A single tight paragraph, front-loaded with what the tool does and where its boundary lies, followed by constraints, the sibling route, and the permission note. Every sentence carries information an agent would otherwise have to infer.

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 7-parameter nested mutation tool with an output schema, the description covers scope, ownership precondition, attachment retention, mention/ping defaults implicitly, and required permissions. The presence of an output schema removes any need to explain the returned message.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents every field including the add_files and update_attachments sub-objects. The description contributes additional meaning by clarifying that content/embeds are replaced rather than merged and that existing attachments are never dropped, which is not stated in the schema. Marginal rather than extensive added semantics keeps it at 4.

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 ('Edit a message the bot sent') and enumerates the editable surfaces: content, embeds, new file uploads, and existing-attachment description/spoiler flags. It explicitly separates itself from discord_send_message by naming that sibling, so no schema comparison is needed to pick the right tool.

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?

States the hard ownership precondition ('Discord only lets a bot edit its own messages') and routes the agent to discord_send_message for the create case. It also gives a when-not signal for attachment removal ('they cannot be removed with this tool'), leaving no ambiguity about the negative case.

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