discord-mcp

channels_modify

Idempotent

Update existing channel settings (name, category, NSFW, slowmode, forum tags) by passing only the fields you want to change.

Instructions

Purpose: Update an existing channel's settings. Pass only the fields you want to change.

When to use:

Rename, move under a category, toggle nsfw, change slowmode, retag a forum channel.

When NOT to use:

Permission overwrites for a single role/user → use channels_modify_permissions.
Deleting → use channels_delete.

Field applicability mirrors channels_create_guild_channel. Discord ignores fields that do not apply to the channel type.

Forum tags: Read channels_get first. available_tags is the complete desired set: keep IDs for existing tags; omit id only for additions. Every omitted existing ID must be listed in remove_available_tag_ids. Omitted emoji/moderated fields are preserved for existing IDs. The tool reads the current set before PATCH and refuses an incomplete state.

Emoji: emoji_id is a guild emoji ID; application emoji compatibility is not guaranteed. To reuse application emoji artwork, upload it with emojis_create and use the resulting guild emoji ID. Set either emoji_id or emoji_name; set both to null to clear.

Verification: Tag changes are read back after PATCH. After editing forum tags, read existing posts with channels_get or the active/archived thread lists to confirm their applied_tags still reference the retained IDs. Verification failure means PATCH succeeded: read current state before retrying.

Returns: {id, name, type, parent_id, available_tags?, applied_tags?, tags_verified?}. tags_verified:true confirms this channel's tag readback only. name is null for DM / unnamed group DM channels.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	New channel name
`nsfw`	No
`type`	No	Convert text↔announcement only (Discord limitation)
`flags`	No	Channel flags bitfield
`topic`	No
`bitrate`	No
`position`	No
`parent_id`	No
`channel_id`	Yes	Channel to modify
`rtc_region`	No
`user_limit`	No
`applied_tags`	No	Complete desired tag IDs on a forum/media post. [] explicitly removes all post tags; omit to preserve.
`audit_reason`	No	Reason recorded in audit log (X-Audit-Log-Reason header)
`available_tags`	No	Complete desired tag set. Keep existing IDs; omit id for additions. Read channels_get first.
`default_sort_order`	No
`video_quality_mode`	No
`rate_limit_per_user`	No
`default_forum_layout`	No
`permission_overwrites`	No
`default_reaction_emoji`	No
`remove_available_tag_ids`	No	Explicit IDs to delete from the current set; requires available_tags with those IDs omitted.
`default_auto_archive_duration`	No
`default_thread_rate_limit_per_user`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv0.28.0Sep 15, 2026

addedInput schema / properties / applied_tags

Added value: +{
+  "description": "Complete desired tag IDs on a forum/media post. [] explicitly removes all post tags; omit to preserve.",
+  "items": {
+    "pattern": "^\\d{17,20}$",
+    "type": "string"
+  },
+  "maxItems": 5,
+  "type": "array"
+}

addedInput schema / properties / available_tags / description

Added value: +"Complete desired tag set. Keep existing IDs; omit id for additions. Read channels_get first."

changedInput schema / properties / available_tags / items / properties / emoji_id / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "pattern": "^\\d{17,20}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / available_tags / items / properties / emoji_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedInput schema / properties / available_tags / items / properties / emoji_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
addedInput schema / properties / available_tags / items / properties / id / pattern
```
Added value: +"^\\d{17,20}$"
```
addedInput schema / properties / available_tags / items / properties / name / maxLength
```
Added value: +20
```
addedInput schema / properties / available_tags / maxItems
```
Added value: +20
```

changedInput schema / properties / default_reaction_emoji / anyOf

Previous value: -[
-  {
-    "properties": {
-      "emoji_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "emoji_name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "emoji_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "emoji_name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / remove_available_tag_ids

Added value: +{
+  "description": "Explicit IDs to delete from the current set; requires available_tags with those IDs omitted.",
+  "items": {
+    "pattern": "^\\d{17,20}$",
+    "type": "string"
+  },
+  "maxItems": 20,
+  "type": "array"
+}

removedInput schema / properties / rtc_region / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / rtc_region / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "additionalProperties": {},
-    "properties": {
-      "id": {
-        "description": "Discord channel ID (snowflake)",
-        "pattern": "^\\d{17,20}$",
-        "type": "string"
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "parent_id": {
-        "anyOf": [
-          {
-            "description": "Discord channel ID (snowflake)",
-            "pattern": "^\\d{17,20}$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "type": {
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "type",
-      "parent_id"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "category": {
-        "enum": [
-          "client",
-          "server"
-        ],
-        "type": "string"
-      },
-      "code": {
-        "type": "string"
-      },
-      "recovery_hint": {
-        "type": "string"
-      },
-      "retriable": {
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "code",
-      "retriable",
-      "category",
-      "recovery_hint"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "additionalProperties": {},
+    "properties": {
+      "applied_tags": {
+        "description": "Tag IDs applied to a forum/media post, when returned by Discord",
+        "items": {
+          "pattern": "^\\d{17,20}$",
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "available_tags": {
+        "description": "Complete forum/media tags, including IDs, names, moderation and emoji fields, when returned by Discord",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "emoji_id": {
+              "anyOf": [
+                {
+                  "pattern": "^\\d{17,20}$",
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "emoji_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "id": {
+              "pattern": "^\\d{17,20}$",
+              "type": "string"
+            },
+            "moderated": {
+              "type": "boolean"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "moderated",
+            "emoji_id",
+            "emoji_name"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "id": {
+        "description": "Discord channel ID (snowflake)",
+        "pattern": "^\\d{17,20}$",
+        "type": "string"
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "parent_id": {
+        "anyOf": [
+          {
+            "description": "Discord channel ID (snowflake)",
+            "pattern": "^\\d{17,20}$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "tags_verified": {
+        "const": true,
+        "type": "boolean"
+      },
+      "type": {
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "type",
+      "parent_id"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "category": {
+        "enum": [
+          "client",
+          "server"
+        ],
+        "type": "string"
+      },
+      "code": {
+        "type": "string"
+      },
+      "recovery_hint": {
+        "type": "string"
+      },
+      "retriable": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "code",
+      "retriable",
+      "category",
+      "recovery_hint"
+    ],
+    "type": "object"
+  }
+]

First observedv0.22.0Aug 14, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations, the description reveals important runtime behavior: Discord ignores non-applicable fields, forum tag updates require reading the current set first and refuse incomplete states, verification readback occurs after PATCH, and verification failure still means PATCH succeeded. These are non-obvious behavioral details that materially affect correct invocation.

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?

The description is long but tightly organized with bolded sections: Purpose, When to use, When NOT to use, Field applicability, Forum tags, Emoji, Verification, and Returns. The purpose is front-loaded, and every section earns its place given the tool's complexity. No filler or redundant restatement of the schema.

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 23-parameter mutation tool with low schema coverage, the description is remarkably complete. It covers purpose, exclusions, prerequisites (read channels_get first), complex forum-tag semantics, emoji constraints, verification behavior, and return shape. The existence of an output schema reduces the need to describe returns, but the description still provides useful verification-related return details.

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 only 35%, so the description carries significant weight. It adds crucial semantics for available_tags and remove_available_tag_ids (complete desired set, preserving omitted fields, requiring prior read), for emoji_id vs emoji_name (guild emoji IDs only, null clears), and for partial updates ('Pass only the fields you want to change'). Some parameters like bitrate, position, and default_forum_layout are not individually explained, but the cross-reference to channels_create_guild_channel partially compensates.

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 description opens with a specific verb and resource: "Update an existing channel's settings." It clearly distinguishes itself from sibling tools by explicitly naming what it is not for (permission overwrites → channels_modify_permissions, deletion → channels_delete), so an agent can differentiate it without inspecting other schemas.

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?

The description provides an explicit 'When to use' section listing concrete scenarios (rename, move under category, toggle nsfw, change slowmode, retag forum channels) and a 'When NOT to use' section naming exact alternatives. This leaves little to inference.

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

Deploy Server