discord-mcp

discord_send_message

Send text, embeds, polls, files, stickers, or replies to a Discord channel or thread, with mention and notification controls and nonce-based retry to avoid duplicates.

Instructions

Send a message to a channel or thread. It can carry text, embeds, a poll, files from the local machine, a reply to an existing message, stickers (up to 3) and flags (suppress embeds, silent). At least one of content, embeds, sticker_ids, files or poll is required. Mentions do not ping unless allowed_mentions permits it. To change a message already sent use discord_edit_message. A retry without the same nonce posts a second message. Bot permissions it may need: View Channel, Send Messages, Attach Files, Embed Links, Send Polls, Send TTS Messages, Read Message History, Send Messages in Threads, Use External Stickers, Mention Everyone. Changes Discord data and is not idempotent; check the result before retrying.

Input Schema

Name	Required	Description
`tts`	No	Whether this message should be spoken using text-to-speech (default false)
`poll`	No	Poll to create with the message
`files`	No	Local files to upload as message attachments
`flags`	No	Message flags bitfield. 4 suppresses link embeds, 4096 sends without push or desktop notifications; add them to set both (4100). No other flags are accepted.
`nonce`	No	Pass the nonce from an uncertain result to retry without a duplicate
`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
`channel_id`	Yes	ID of the channel or thread to send the message in
`sticker_ids`	No	Array of up to 3 sticker IDs to attach to the message
`allowed_mentions`	No	Allowed mentions object controlling which role, user, or @everyone pings produce notifications; defaults to no pings
`message_reference`	No	Message reference object for replying to an earlier message

Output Schema

Name	Required	Description	Default
`message`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed49 schema fields changedv0.1.2Nov 4, 2026
- 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 to send the message in"
```
- 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 / files / description
```
Added value: +"Local files to upload as message attachments"
```
- addedInput schema / properties / files / items / description
```
Added value: +"Local file upload specification with path and optional metadata"
```
- addedInput schema / properties / files / items / properties / content_type / description
```
Added value: +"MIME type of the file; detected from the file content when omitted"
```
- addedInput schema / properties / files / items / properties / description / description
```
Added value: +"Accessibility alt-text description for the attachment (up to 1024 characters)"
```
- addedInput schema / properties / files / items / properties / filename / description
```
Added value: +"Override filename sent to Discord; defaults to the basename of path"
```
- addedInput schema / properties / files / items / properties / is_spoiler / description
```
Added value: +"Whether to mark the attachment as a spoiler; defaults to false"
```
- addedInput schema / properties / files / items / properties / title / description
```
Added value: +"Display title for the uploaded file"
```
- changedInput schema / properties / flags / description
```
Previous value: -"Message flags bitfield"New value: +"Message flags bitfield. 4 suppresses link embeds, 4096 sends without push or desktop notifications; add them to set both (4100). No other flags are accepted."
```
- addedInput schema / properties / message_reference / description
```
Added value: +"Message reference object for replying to an earlier message"
```
- addedInput schema / properties / message_reference / properties / fail_if_not_exists / description
```
Added value: +"Whether to fail sending if the referenced message does not exist (default true)"
```
- addedInput schema / properties / message_reference / properties / message_id / description
```
Added value: +"ID of the original message being replied to"
```
- addedInput schema / properties / poll / description
```
Added value: +"Poll to create with the message"
```
- addedInput schema / properties / poll / properties / allow_multiselect / description
```
Added value: +"Whether voters can select more than one answer (default false)"
```
- addedInput schema / properties / poll / properties / answers / description
```
Added value: +"Between 1 and 10 possible answers for voters to choose from"
```
- addedInput schema / properties / poll / properties / answers / items / description
```
Added value: +"One answer choice"
```
- addedInput schema / properties / poll / properties / answers / items / properties / poll_media / description
```
Added value: +"Answer choice display content (text and optional emoji)"
```
- addedInput schema / properties / poll / properties / answers / items / properties / poll_media / properties / emoji / description
```
Added value: +"Optional emoji display for the answer"
```
- addedInput schema / properties / poll / properties / answers / items / properties / poll_media / properties / emoji / properties / id / description
```
Added value: +"ID of a custom guild emoji"
```
- addedInput schema / properties / poll / properties / answers / items / properties / poll_media / properties / emoji / properties / name / description
```
Added value: +"Unicode emoji character or custom emoji name"
```
- addedInput schema / properties / poll / properties / answers / items / properties / poll_media / properties / text / description
```
Added value: +"Answer text (1-55 characters)"
```
- changedInput schema / properties / poll / properties / duration / description
```
Previous value: -"Poll duration in hours"New value: +"Poll duration in hours up to 32 days (768 hours; default is 24 hours)"
```
- changedInput schema / properties / poll / properties / layout_type / description
```
Previous value: -"1 for the default poll layout"New value: +"Poll layout type (1 for standard default poll layout)"
```
- addedInput schema / properties / poll / properties / question / description
```
Added value: +"Poll question prompt"
```
- addedInput schema / properties / poll / properties / question / properties / text / description
```
Added value: +"Poll question title (1-300 characters)"
```
- addedInput schema / properties / sticker_ids / description
```
Added value: +"Array of up to 3 sticker IDs to attach to the message"
```
- addedInput schema / properties / sticker_ids / items / description
```
Added value: +"Sticker snowflake ID"
```
- addedInput schema / properties / tts / description
```
Added value: +"Whether this message should be spoken using text-to-speech (default false)"
```
- 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.6/5.0

Behavior4/5

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

Beyond the annotations, it discloses the bot permission set required (View Channel, Attach Files, Send Polls, etc.), that mentions do not ping unless allowed_mentions permits, and that a retry without the same nonce creates a duplicate. The final sentence partly restates idempotentHint=false and destructiveHint=false, and nothing is said about rate limits, so it stops short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Content is front-loaded: capability, then constraints, then alternative, then retry behavior, then permissions. The opening enumeration is dense but each clause maps to a real parameter, though the permission list is a long tail that could be trimmed.

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 an 11-parameter, nested-payload write tool with an output schema and full annotations, the description covers the gaps that matter: minimum payload requirement, ping semantics, retry/nonce hazard, and permission prerequisites. An agent has enough to call it correctly without opening anything else.

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 coverage is 100%, so the baseline is 3; the description earns one more by grouping the parameters into recognizable payload categories and stating the mutual-exclusivity/at-least-one rule that the schema's single required field does not convey. It does not add format or validation detail beyond the schema.

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?

The first sentence names a specific verb and resource (send a message to a channel or thread) and the rest enumerates the payloads it can carry: text, embeds, poll, files, reply, stickers, flags. The closing pointer to discord_edit_message clearly separates it from the closest sibling operation.

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?

It names the alternative explicitly ("To change a message already sent use discord_edit_message") and states a hard precondition that the schema does not encode: "At least one of content, embeds, sticker_ids, files or poll is required." It also gives retry guidance tied to the nonce, which tells the agent when a blind retry is wrong.

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