discord-mcp

permissions_explain

Read-onlyIdempotent

Explain effective Discord permissions for a member or role. Verify if an action is allowed and diagnose why Discord permits or denies it, with a decision trace and missing permissions.

Instructions

Purpose: Explain effective Discord permissions for one guild member or one role.

When to use:

Verify a permission or supported action before a write.
Diagnose why Discord allows, denies, or cannot conclusively evaluate an action.

When NOT to use:

Mutating roles or overwrites; this tool is read-only.
Treating a partial result as permission to write.

Returns: {allowed, effective_permissions, missing_permissions, ineffective_permissions, decision_trace, role_hierarchy_check, warnings, confidence}. allowed:null means Discord did not expose enough evidence for a safe conclusion.

Input Schema

TableJSON Schema

Name	Required	Description
`action`	No	Optional high-level action; translated into its required permission constants
`role_id`	No	Role to evaluate; mutually exclusive with user_id
`user_id`	No	Member to evaluate; mutually exclusive with role_id
`guild_id`	Yes	Guild whose permission state should be evaluated
`channel_id`	No	Optional guild channel or thread scope. Required for channel actions.
`target_role_id`	No	Target role; required for assign_role or remove_role
`target_user_id`	No	Target member; required for kick_member, ban_member, or timeout_member
`requested_permissions`	No	Discord permission constants such as VIEW_CHANNEL or SEND_MESSAGES

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.28.0Sep 15, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "additionalProperties": {},
-    "properties": {
-      "action": {
-        "anyOf": [
-          {
-            "enum": [
-              "view_channel",
-              "send_messages",
-              "manage_channel",
-              "assign_role",
-              "remove_role",
-              "kick_member",
-              "ban_member",
-              "timeout_member"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "administrator": {
-        "type": "boolean"
-      },
-      "allowed": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "applied_role_ids": {
-        "items": {
-          "description": "Discord role ID",
-          "pattern": "^\\d{17,20}$",
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "base_permissions": {
-        "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
-        "pattern": "^\\d+$",
-        "type": "string"
-      },
-      "channel_id": {
-        "anyOf": [
-          {
-            "description": "Discord channel ID (snowflake)",
-            "pattern": "^\\d{17,20}$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "confidence": {
-        "enum": [
-          "complete",
-          "partial"
-        ],
-        "type": "string"
-      },
-      "decision_trace": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "after": {
-              "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
-              "pattern": "^\\d+$",
-              "type": "string"
-            },
-            "allow": {
-              "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
-              "pattern": "^\\d+$",
-              "type": "string"
-            },
-            "before": {
-              "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
-              "pattern": "^\\d+$",
-              "type": "string"
-            },
-            "deny": {
-              "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
-              "pattern": "^\\d+$",
-              "type": "string"
-            },
-            "note": {
-              "type": "string"
-            },
-            "stage": {
-              "enum": [
-                "guild_everyone",
-                "guild_roles",
-                "guild_owner",
-                "administrator",
-                "channel_everyone",
-                "channel_roles",
-                "channel_member",
-                "member_timeout"
-              ],
-              "type": "string"
-            }
-          },
-          "required": [
-            "stage",
-            "before",
-            "allow",
-            "deny",
-            "after",
-            "note"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "effective_permissions": {
-        "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
-        "pattern": "^\\d+$",
-        "type": "string"
-      },
-      "guild_id": {
-        "description": "Discord guild (server) ID",
-        "pattern": "^\\d{17,20}$",
-        "type": "string"
-      },
-      "guild_owner": {
-        "type": "boolean"
-      },
-      "implicit_denies": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "missing_prerequisites": {
-              "items": {
-                "enum": [
-                  "CREATE_INSTANT_INVITE",
-                  "KICK_MEMBERS",
-                  "BAN_MEMBERS",
-                  "ADMINISTRATOR",
-                  "MANAGE_CHANNELS",
-                  "MANAGE_GUILD",
-                  "ADD_REACTIONS",
-                  "VIEW_AUDIT_LOG",
-                  "PRIORITY_SPEAKER",
-                  "STREAM",
-                  "VIEW_CHANNEL",
-                  "SEND_MESSAGES",
-                  "SEND_TTS_MESSAGES",
-                  "MANAGE_MESSAGES",
-                  "EMBED_LINKS",
-                  "ATTACH_FILES",
-                  "READ_MESSAGE_HISTORY",
-                  "MENTION_EVERYONE",
-                  "USE_EXTERNAL_EMOJIS",
-                  "VIEW_GUILD_INSIGHTS",
-                  "CONNECT",
-                  "SPEAK",
-                  "MUTE_MEMBERS",
-                  "DEAFEN_MEMBERS",
-                  "MOVE_MEMBERS",
-                  "USE_VAD",
-                  "CHANGE_NICKNAME",
-                  "MANAGE_NICKNAMES",
-                  "MANAGE_ROLES",
-                  "MANAGE_WEBHOOKS",
-                  "MANAGE_EMOJIS_AND_STICKERS",
-                  "MANAGE_GUILD_EXPRESSIONS",
-                  "USE_APPLICATION_COMMANDS",
-                  "REQUEST_TO_SPEAK",
-                  "MANAGE_EVENTS",
-                  "MANAGE_THREADS",
-                  "CREATE_PUBLIC_THREADS",
-                  "CREATE_PRIVATE_THREADS",
-                  "USE_EXTERNAL_STICKERS",
-                  "SEND_MESSAGES_IN_THREADS",
-                  "USE_EMBEDDED_ACTIVITIES",
-                  "MODERATE_MEMBERS",
-                  "VIEW_CREATOR_MONETIZATION_ANALYTICS",
-                  "USE_SOUNDBOARD",
-                  "CREATE_GUILD_EXPRESSIONS",
-                  "CREATE_EVENTS",
-                  "USE_EXTERNAL_SOUNDS",
-                  "SEND_VOICE_MESSAGES",
-                  "SET_VOICE_CHANNEL_STATUS",
-                  "SEND_POLLS",
-                  "USE_EXTERNAL_APPS",
-                  "PIN_MESSAGES",
-                  "BYPASS_SLOWMODE"
-                ],
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "permission": {
-              "enum": [
-                "CREATE_INSTANT_INVITE",
-                "KICK_MEMBERS",
-                "BAN_MEMBERS",
-                "ADMINISTRATOR",
-                "MANAGE_CHANNELS",
-                "MANAGE_GUILD",
-                "ADD_REACTIONS",
-                "VIEW_AUDIT_LOG",
-                "PRIORITY_SPEAKER",
-                "STREAM",
-                "VIEW_CHANNEL",
-                "SEND_MESSAGES",
-                "SEND_TTS_MESSAGES",
-                "MANAGE_MESSAGES",
-                "EMBED_LINKS",
-                "ATTACH_FILES",
-                "READ_MESSAGE_HISTORY",
-                "MENTION_EVERYONE",
-                "USE_EXTERNAL_EMOJIS",
-                "VIEW_GUILD_INSIGHTS",
-                "CONNECT",
-                "SPEAK",
-                "MUTE_MEMBERS",
-                "DEAFEN_MEMBERS",
-                "MOVE_MEMBERS",
-                "USE_VAD",
-                "CHANGE_NICKNAME",
-                "MANAGE_NICKNAMES",
-                "MANAGE_ROLES",
-                "MANAGE_WEBHOOKS",
-                "MANAGE_EMOJIS_AND_STICKERS",
-                "MANAGE_GUILD_EXPRESSIONS",
-                "USE_APPLICATION_COMMANDS",
-                "REQUEST_TO_SPEAK",
-                "MANAGE_EVENTS",
-                "MANAGE_THREADS",
-                "CREATE_PUBLIC_THREADS",
-                "CREATE_PRIVATE_THREADS",
-                "USE_EXTERNAL_STICKERS",
-                "SEND_MESSAGES_IN_THREADS",
-                "USE_EMBEDDED_ACTIVITIES",
-                "MODERATE_MEMBERS",
-                "VIEW_CREATOR_MONETIZATION_ANALYTICS",
-                "USE_SOUNDBOARD",
-                "CREATE_GUILD_EXPRESSIONS",
-                "CREATE_EVENTS",
-                "USE_EXTERNAL_SOUNDS",
-                "SEND_VOICE_MESSAGES",
-                "SET_VOICE_CHANNEL_STATUS",
-                "SEND_POLLS",
-                "USE_EXTERNAL_APPS",
-                "PIN_MESSAGES",
-                "BYPASS_SLOWMODE"
-              ],
-              "type": "string"
-            },
-            "reason": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "permission",
-            "missing_prerequisites",
-            "reason"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "ineffective_permissions": {
-        "items": {
-          "enum": [
-            "CREATE_INSTANT_INVITE",
-            "KICK_MEMBERS",
-            "BAN_MEMBERS",
-            "ADMINISTRATOR",
-            "MANAGE_CHANNELS",
-            "MANAGE_GUILD",
-            "ADD_REACTIONS",
-            "VIEW_AUDIT_LOG",
-            "PRIORITY_SPEAKER",
-            "STREAM",
-            "VIEW_CHANNEL",
-            "SEND_MESSAGES",
-            "SEND_TTS_MESSAGES",
-            "MANAGE_MESSAGES",
-            "EMBED_LINKS",
-            "ATTACH_FILES",
-            "READ_MESSAGE_HISTORY",
-            "MENTION_EVERYONE",
-            "USE_EXTERNAL_EMOJIS",
-            "VIEW_GUILD_INSIGHTS",
-            "CONNECT",
-            "SPEAK",
-            "MUTE_MEMBERS",
-            "DEAFEN_MEMBERS",
-            "MOVE_MEMBERS",
-            "USE_VAD",
-            "CHANGE_NICKNAME",
-            "MANAGE_NICKNAMES",
-            "MANAGE_ROLES",
-            "MANAGE_WEBHOOKS",
-            "MANAGE_EMOJIS_AND_STICKERS",
-            "MANAGE_GUILD_EXPRESSIONS",
-            "USE_APPLICATION_COMMANDS",
-            "REQUEST_TO_SPEAK",
-            "MANAGE_EVENTS",
-            "MANAGE_THREADS",
-            "CREATE_PUBLIC_THREADS",
-            "CREATE_PRIVATE_THREADS",
-            "USE_EXTERNAL_STICKERS",
-            "SEND_MESSAGES_IN_THREADS",
-            "USE_EMBEDDED_ACTIVITIES",
-            "MODERATE_MEMBERS",
-            "VIEW_CREATOR_MONETIZATION_ANALYTICS",
-            "USE_SOUNDBOARD",
-            "CREATE_GUILD_EXPRESSIONS",
-            "CREATE_EVENTS",
-            "USE_EXTERNAL_SOUNDS",
-            "SEND_VOICE_MESSAGES",
-            "SET_VOICE_CHANNEL_STATUS",
-            "SEND_POLLS",
-            "USE_EXTERNAL_APPS",
-            "PIN_MESSAGES",
-            "BYPASS_SLOWMODE"
-          ],
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "missing_permissions": {
-        "items": {
-          "enum": [
-            "CREATE_INSTANT_INVITE",
-            "KICK_MEMBERS",
-            "BAN_MEMBERS",
-            "ADMINISTRATOR",
-            "MANAGE_CHANNELS",
-            "MANAGE_GUILD",
-            "ADD_REACTIONS",
-            "VIEW_AUDIT_LOG",
-            "PRIORITY_SPEAKER",
-            "STREAM",
-            "VIEW_CHANNEL",
-            "SEND_MESSAGES",
-            "SEND_TTS_MESSAGES",
-            "MANAGE_MESSAGES",
-            "EMBED_LINKS",
-            "ATTACH_FILES",
-            "READ_MESSAGE_HISTORY",
-            "MENTION_EVERYONE",
-            "USE_EXTERNAL_EMOJIS",
-            "VIEW_GUILD_INSIGHTS",
-            "CONNECT",
-            "SPEAK",
-            "MUTE_MEMBERS",
-            "DEAFEN_MEMBERS",
-            "MOVE_MEMBERS",
-            "USE_VAD",
-            "CHANGE_NICKNAME",
-            "MANAGE_NICKNAMES",
-            "MANAGE_ROLES",
-            "MANAGE_WEBHOOKS",
-            "MANAGE_EMOJIS_AND_STICKERS",
-            "MANAGE_GUILD_EXPRESSIONS",
-            "USE_APPLICATION_COMMANDS",
-            "REQUEST_TO_SPEAK",
-            "MANAGE_EVENTS",
-            "MANAGE_THREADS",
-            "CREATE_PUBLIC_THREADS",
-            "CREATE_PRIVATE_THREADS",
-            "USE_EXTERNAL_STICKERS",
-            "SEND_MESSAGES_IN_THREADS",
-            "USE_EMBEDDED_ACTIVITIES",
-            "MODERATE_MEMBERS",
-            "VIEW_CREATOR_MONETIZATION_ANALYTICS",
-            "USE_SOUNDBOARD",
-            "CREATE_GUILD_EXPRESSIONS",
-            "CREATE_EVENTS",
-            "USE_EXTERNAL_SOUNDS",
-            "SEND_VOICE_MESSAGES",
-            "SET_VOICE_CHANNEL_STATUS",
-            "SEND_POLLS",
-            "USE_EXTERNAL_APPS",
-            "PIN_MESSAGES",
-            "BYPASS_SLOWMODE"
-          ],
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "permission_source_channel_id": {
-        "anyOf": [
-          {
-            "description": "Discord channel ID (snowflake)",
-            "pattern": "^\\d{17,20}$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "requested_permissions": {
-        "items": {
-          "enum": [
-            "CREATE_INSTANT_INVITE",
-            "KICK_MEMBERS",
-            "BAN_MEMBERS",
-            "ADMINISTRATOR",
-            "MANAGE_CHANNELS",
-            "MANAGE_GUILD",
-            "ADD_REACTIONS",
-            "VIEW_AUDIT_LOG",
-            "PRIORITY_SPEAKER",
-            "STREAM",
-            "VIEW_CHANNEL",
-            "SEND_MESSAGES",
-            "SEND_TTS_MESSAGES",
-            "MANAGE_MESSAGES",
-            "EMBED_LINKS",
-            "ATTACH_FILES",
-            "READ_MESSAGE_HISTORY",
-            "MENTION_EVERYONE",
-            "USE_EXTERNAL_EMOJIS",
-            "VIEW_GUILD_INSIGHTS",
-            "CONNECT",
-            "SPEAK",
-            "MUTE_MEMBERS",
-            "DEAFEN_MEMBERS",
-            "MOVE_MEMBERS",
-            "USE_VAD",
-            "CHANGE_NICKNAME",
-            "MANAGE_NICKNAMES",
-            "MANAGE_ROLES",
-            "MANAGE_WEBHOOKS",
-            "MANAGE_EMOJIS_AND_STICKERS",
-            "MANAGE_GUILD_EXPRESSIONS",
-            "USE_APPLICATION_COMMANDS",
-            "REQUEST_TO_SPEAK",
-            "MANAGE_EVENTS",
-            "MANAGE_THREADS",
-            "CREATE_PUBLIC_THREADS",
-            "CREATE_PRIVATE_THREADS",
-            "USE_EXTERNAL_STICKERS",
-            "SEND_MESSAGES_IN_THREADS",
-            "USE_EMBEDDED_ACTIVITIES",
-            "MODERATE_MEMBERS",
-            "VIEW_CREATOR_MONETIZATION_ANALYTICS",
-            "USE_SOUNDBOARD",
-            "CREATE_GUILD_EXPRESSIONS",
-            "CREATE_EVENTS",
-            "USE_EXTERNAL_SOUNDS",
-            "SEND_VOICE_MESSAGES",
-            "SET_VOICE_CHANNEL_STATUS",
-            "SEND_POLLS",
-            "USE_EXTERNAL_APPS",
-            "PIN_MESSAGES",
-            "BYPASS_SLOWMODE"
-          ],
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "role_hierarchy_check": {
-        "additionalProperties": false,
-        "properties": {
-          "actor_top_role_id": {
-            "anyOf": [
-              {
-                "description": "Discord role ID",
-                "pattern": "^\\d{17,20}$",
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "allowed": {
-            "anyOf": [
-              {
-                "type": "boolean"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "reason": {
-            "type": "string"
-          },
-          "status": {
-            "enum": [
-              "not_applicable",
-              "allowed",
-              "denied",
-              "unknown"
-            ],
-            "type": "string"
-          },
-          "target_top_role_id": {
-            "anyOf": [
-              {
-                "description": "Discord role ID",
-                "pattern": "^\\d{17,20}$",
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          }
-        },
-        "required": [
-          "status",
-          "allowed",
-          "actor_top_role_id",
-          "target_top_role_id",
-          "reason"
-        ],
-        "type": "object"
-      },
-      "subject_id": {
-        "description": "Discord member or role ID",
-        "pattern": "^\\d{17,20}$",
-        "type": "string"
-      },
-      "subject_timed_out": {
-        "type": "boolean"
-      },
-      "subject_type": {
-        "enum": [
-          "member",
-          "role"
-        ],
-        "type": "string"
-      },
-      "unknown_permission_bits": {
-        "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
-        "pattern": "^\\d+$",
-        "type": "string"
-      },
-      "warnings": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "guild_id",
-      "channel_id",
-      "permission_source_channel_id",
-      "subject_type",
-      "subject_id",
-      "action",
-      "requested_permissions",
-      "allowed",
-      "base_permissions",
-      "effective_permissions",
-      "unknown_permission_bits",
-      "missing_permissions",
-      "ineffective_permissions",
-      "implicit_denies",
-      "administrator",
-      "guild_owner",
-      "subject_timed_out",
-      "applied_role_ids",
-      "decision_trace",
-      "role_hierarchy_check",
-      "warnings",
-      "confidence"
-    ],
-    "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": {
+      "action": {
+        "anyOf": [
+          {
+            "enum": [
+              "view_channel",
+              "send_messages",
+              "manage_channel",
+              "assign_role",
+              "remove_role",
+              "kick_member",
+              "ban_member",
+              "timeout_member"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "administrator": {
+        "type": "boolean"
+      },
+      "allowed": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "applied_role_ids": {
+        "items": {
+          "description": "Discord role ID",
+          "pattern": "^\\d{17,20}$",
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "base_permissions": {
+        "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
+        "pattern": "^\\d+$",
+        "type": "string"
+      },
+      "channel_id": {
+        "anyOf": [
+          {
+            "description": "Discord channel ID (snowflake)",
+            "pattern": "^\\d{17,20}$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "confidence": {
+        "enum": [
+          "complete",
+          "partial"
+        ],
+        "type": "string"
+      },
+      "decision_trace": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "after": {
+              "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
+              "pattern": "^\\d+$",
+              "type": "string"
+            },
+            "allow": {
+              "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
+              "pattern": "^\\d+$",
+              "type": "string"
+            },
+            "before": {
+              "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
+              "pattern": "^\\d+$",
+              "type": "string"
+            },
+            "deny": {
+              "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
+              "pattern": "^\\d+$",
+              "type": "string"
+            },
+            "note": {
+              "type": "string"
+            },
+            "stage": {
+              "enum": [
+                "guild_everyone",
+                "guild_roles",
+                "guild_owner",
+                "administrator",
+                "channel_everyone",
+                "channel_roles",
+                "channel_member",
+                "member_timeout"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "stage",
+            "before",
+            "allow",
+            "deny",
+            "after",
+            "note"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "effective_permissions": {
+        "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
+        "pattern": "^\\d+$",
+        "type": "string"
+      },
+      "guild_id": {
+        "description": "Discord guild (server) ID",
+        "pattern": "^\\d{17,20}$",
+        "type": "string"
+      },
+      "guild_owner": {
+        "type": "boolean"
+      },
+      "implicit_denies": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "missing_prerequisites": {
+              "items": {
+                "enum": [
+                  "CREATE_INSTANT_INVITE",
+                  "KICK_MEMBERS",
+                  "BAN_MEMBERS",
+                  "ADMINISTRATOR",
+                  "MANAGE_CHANNELS",
+                  "MANAGE_GUILD",
+                  "ADD_REACTIONS",
+                  "VIEW_AUDIT_LOG",
+                  "PRIORITY_SPEAKER",
+                  "STREAM",
+                  "VIEW_CHANNEL",
+                  "SEND_MESSAGES",
+                  "SEND_TTS_MESSAGES",
+                  "MANAGE_MESSAGES",
+                  "EMBED_LINKS",
+                  "ATTACH_FILES",
+                  "READ_MESSAGE_HISTORY",
+                  "MENTION_EVERYONE",
+                  "USE_EXTERNAL_EMOJIS",
+                  "VIEW_GUILD_INSIGHTS",
+                  "CONNECT",
+                  "SPEAK",
+                  "MUTE_MEMBERS",
+                  "DEAFEN_MEMBERS",
+                  "MOVE_MEMBERS",
+                  "USE_VAD",
+                  "CHANGE_NICKNAME",
+                  "MANAGE_NICKNAMES",
+                  "MANAGE_ROLES",
+                  "MANAGE_WEBHOOKS",
+                  "MANAGE_EMOJIS_AND_STICKERS",
+                  "MANAGE_GUILD_EXPRESSIONS",
+                  "USE_APPLICATION_COMMANDS",
+                  "REQUEST_TO_SPEAK",
+                  "MANAGE_EVENTS",
+                  "MANAGE_THREADS",
+                  "CREATE_PUBLIC_THREADS",
+                  "CREATE_PRIVATE_THREADS",
+                  "USE_EXTERNAL_STICKERS",
+                  "SEND_MESSAGES_IN_THREADS",
+                  "USE_EMBEDDED_ACTIVITIES",
+                  "MODERATE_MEMBERS",
+                  "VIEW_CREATOR_MONETIZATION_ANALYTICS",
+                  "USE_SOUNDBOARD",
+                  "CREATE_GUILD_EXPRESSIONS",
+                  "CREATE_EVENTS",
+                  "USE_EXTERNAL_SOUNDS",
+                  "SEND_VOICE_MESSAGES",
+                  "SET_VOICE_CHANNEL_STATUS",
+                  "SEND_POLLS",
+                  "USE_EXTERNAL_APPS",
+                  "PIN_MESSAGES",
+                  "BYPASS_SLOWMODE"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "permission": {
+              "enum": [
+                "CREATE_INSTANT_INVITE",
+                "KICK_MEMBERS",
+                "BAN_MEMBERS",
+                "ADMINISTRATOR",
+                "MANAGE_CHANNELS",
+                "MANAGE_GUILD",
+                "ADD_REACTIONS",
+                "VIEW_AUDIT_LOG",
+                "PRIORITY_SPEAKER",
+                "STREAM",
+                "VIEW_CHANNEL",
+                "SEND_MESSAGES",
+                "SEND_TTS_MESSAGES",
+                "MANAGE_MESSAGES",
+                "EMBED_LINKS",
+                "ATTACH_FILES",
+                "READ_MESSAGE_HISTORY",
+                "MENTION_EVERYONE",
+                "USE_EXTERNAL_EMOJIS",
+                "VIEW_GUILD_INSIGHTS",
+                "CONNECT",
+                "SPEAK",
+                "MUTE_MEMBERS",
+                "DEAFEN_MEMBERS",
+                "MOVE_MEMBERS",
+                "USE_VAD",
+                "CHANGE_NICKNAME",
+                "MANAGE_NICKNAMES",
+                "MANAGE_ROLES",
+                "MANAGE_WEBHOOKS",
+                "MANAGE_EMOJIS_AND_STICKERS",
+                "MANAGE_GUILD_EXPRESSIONS",
+                "USE_APPLICATION_COMMANDS",
+                "REQUEST_TO_SPEAK",
+                "MANAGE_EVENTS",
+                "MANAGE_THREADS",
+                "CREATE_PUBLIC_THREADS",
+                "CREATE_PRIVATE_THREADS",
+                "USE_EXTERNAL_STICKERS",
+                "SEND_MESSAGES_IN_THREADS",
+                "USE_EMBEDDED_ACTIVITIES",
+                "MODERATE_MEMBERS",
+                "VIEW_CREATOR_MONETIZATION_ANALYTICS",
+                "USE_SOUNDBOARD",
+                "CREATE_GUILD_EXPRESSIONS",
+                "CREATE_EVENTS",
+                "USE_EXTERNAL_SOUNDS",
+                "SEND_VOICE_MESSAGES",
+                "SET_VOICE_CHANNEL_STATUS",
+                "SEND_POLLS",
+                "USE_EXTERNAL_APPS",
+                "PIN_MESSAGES",
+                "BYPASS_SLOWMODE"
+              ],
+              "type": "string"
+            },
+            "reason": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "permission",
+            "missing_prerequisites",
+            "reason"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "ineffective_permissions": {
+        "items": {
+          "enum": [
+            "CREATE_INSTANT_INVITE",
+            "KICK_MEMBERS",
+            "BAN_MEMBERS",
+            "ADMINISTRATOR",
+            "MANAGE_CHANNELS",
+            "MANAGE_GUILD",
+            "ADD_REACTIONS",
+            "VIEW_AUDIT_LOG",
+            "PRIORITY_SPEAKER",
+            "STREAM",
+            "VIEW_CHANNEL",
+            "SEND_MESSAGES",
+            "SEND_TTS_MESSAGES",
+            "MANAGE_MESSAGES",
+            "EMBED_LINKS",
+            "ATTACH_FILES",
+            "READ_MESSAGE_HISTORY",
+            "MENTION_EVERYONE",
+            "USE_EXTERNAL_EMOJIS",
+            "VIEW_GUILD_INSIGHTS",
+            "CONNECT",
+            "SPEAK",
+            "MUTE_MEMBERS",
+            "DEAFEN_MEMBERS",
+            "MOVE_MEMBERS",
+            "USE_VAD",
+            "CHANGE_NICKNAME",
+            "MANAGE_NICKNAMES",
+            "MANAGE_ROLES",
+            "MANAGE_WEBHOOKS",
+            "MANAGE_EMOJIS_AND_STICKERS",
+            "MANAGE_GUILD_EXPRESSIONS",
+            "USE_APPLICATION_COMMANDS",
+            "REQUEST_TO_SPEAK",
+            "MANAGE_EVENTS",
+            "MANAGE_THREADS",
+            "CREATE_PUBLIC_THREADS",
+            "CREATE_PRIVATE_THREADS",
+            "USE_EXTERNAL_STICKERS",
+            "SEND_MESSAGES_IN_THREADS",
+            "USE_EMBEDDED_ACTIVITIES",
+            "MODERATE_MEMBERS",
+            "VIEW_CREATOR_MONETIZATION_ANALYTICS",
+            "USE_SOUNDBOARD",
+            "CREATE_GUILD_EXPRESSIONS",
+            "CREATE_EVENTS",
+            "USE_EXTERNAL_SOUNDS",
+            "SEND_VOICE_MESSAGES",
+            "SET_VOICE_CHANNEL_STATUS",
+            "SEND_POLLS",
+            "USE_EXTERNAL_APPS",
+            "PIN_MESSAGES",
+            "BYPASS_SLOWMODE"
+          ],
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "missing_permissions": {
+        "items": {
+          "enum": [
+            "CREATE_INSTANT_INVITE",
+            "KICK_MEMBERS",
+            "BAN_MEMBERS",
+            "ADMINISTRATOR",
+            "MANAGE_CHANNELS",
+            "MANAGE_GUILD",
+            "ADD_REACTIONS",
+            "VIEW_AUDIT_LOG",
+            "PRIORITY_SPEAKER",
+            "STREAM",
+            "VIEW_CHANNEL",
+            "SEND_MESSAGES",
+            "SEND_TTS_MESSAGES",
+            "MANAGE_MESSAGES",
+            "EMBED_LINKS",
+            "ATTACH_FILES",
+            "READ_MESSAGE_HISTORY",
+            "MENTION_EVERYONE",
+            "USE_EXTERNAL_EMOJIS",
+            "VIEW_GUILD_INSIGHTS",
+            "CONNECT",
+            "SPEAK",
+            "MUTE_MEMBERS",
+            "DEAFEN_MEMBERS",
+            "MOVE_MEMBERS",
+            "USE_VAD",
+            "CHANGE_NICKNAME",
+            "MANAGE_NICKNAMES",
+            "MANAGE_ROLES",
+            "MANAGE_WEBHOOKS",
+            "MANAGE_EMOJIS_AND_STICKERS",
+            "MANAGE_GUILD_EXPRESSIONS",
+            "USE_APPLICATION_COMMANDS",
+            "REQUEST_TO_SPEAK",
+            "MANAGE_EVENTS",
+            "MANAGE_THREADS",
+            "CREATE_PUBLIC_THREADS",
+            "CREATE_PRIVATE_THREADS",
+            "USE_EXTERNAL_STICKERS",
+            "SEND_MESSAGES_IN_THREADS",
+            "USE_EMBEDDED_ACTIVITIES",
+            "MODERATE_MEMBERS",
+            "VIEW_CREATOR_MONETIZATION_ANALYTICS",
+            "USE_SOUNDBOARD",
+            "CREATE_GUILD_EXPRESSIONS",
+            "CREATE_EVENTS",
+            "USE_EXTERNAL_SOUNDS",
+            "SEND_VOICE_MESSAGES",
+            "SET_VOICE_CHANNEL_STATUS",
+            "SEND_POLLS",
+            "USE_EXTERNAL_APPS",
+            "PIN_MESSAGES",
+            "BYPASS_SLOWMODE"
+          ],
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "permission_source_channel_id": {
+        "anyOf": [
+          {
+            "description": "Discord channel ID (snowflake)",
+            "pattern": "^\\d{17,20}$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "requested_permissions": {
+        "items": {
+          "enum": [
+            "CREATE_INSTANT_INVITE",
+            "KICK_MEMBERS",
+            "BAN_MEMBERS",
+            "ADMINISTRATOR",
+            "MANAGE_CHANNELS",
+            "MANAGE_GUILD",
+            "ADD_REACTIONS",
+            "VIEW_AUDIT_LOG",
+            "PRIORITY_SPEAKER",
+            "STREAM",
+            "VIEW_CHANNEL",
+            "SEND_MESSAGES",
+            "SEND_TTS_MESSAGES",
+            "MANAGE_MESSAGES",
+            "EMBED_LINKS",
+            "ATTACH_FILES",
+            "READ_MESSAGE_HISTORY",
+            "MENTION_EVERYONE",
+            "USE_EXTERNAL_EMOJIS",
+            "VIEW_GUILD_INSIGHTS",
+            "CONNECT",
+            "SPEAK",
+            "MUTE_MEMBERS",
+            "DEAFEN_MEMBERS",
+            "MOVE_MEMBERS",
+            "USE_VAD",
+            "CHANGE_NICKNAME",
+            "MANAGE_NICKNAMES",
+            "MANAGE_ROLES",
+            "MANAGE_WEBHOOKS",
+            "MANAGE_EMOJIS_AND_STICKERS",
+            "MANAGE_GUILD_EXPRESSIONS",
+            "USE_APPLICATION_COMMANDS",
+            "REQUEST_TO_SPEAK",
+            "MANAGE_EVENTS",
+            "MANAGE_THREADS",
+            "CREATE_PUBLIC_THREADS",
+            "CREATE_PRIVATE_THREADS",
+            "USE_EXTERNAL_STICKERS",
+            "SEND_MESSAGES_IN_THREADS",
+            "USE_EMBEDDED_ACTIVITIES",
+            "MODERATE_MEMBERS",
+            "VIEW_CREATOR_MONETIZATION_ANALYTICS",
+            "USE_SOUNDBOARD",
+            "CREATE_GUILD_EXPRESSIONS",
+            "CREATE_EVENTS",
+            "USE_EXTERNAL_SOUNDS",
+            "SEND_VOICE_MESSAGES",
+            "SET_VOICE_CHANNEL_STATUS",
+            "SEND_POLLS",
+            "USE_EXTERNAL_APPS",
+            "PIN_MESSAGES",
+            "BYPASS_SLOWMODE"
+          ],
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "role_hierarchy_check": {
+        "additionalProperties": false,
+        "properties": {
+          "actor_top_role_id": {
+            "anyOf": [
+              {
+                "description": "Discord role ID",
+                "pattern": "^\\d{17,20}$",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "allowed": {
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          },
+          "status": {
+            "enum": [
+              "not_applicable",
+              "allowed",
+              "denied",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          "target_top_role_id": {
+            "anyOf": [
+              {
+                "description": "Discord role ID",
+                "pattern": "^\\d{17,20}$",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "status",
+          "allowed",
+          "actor_top_role_id",
+          "target_top_role_id",
+          "reason"
+        ],
+        "type": "object"
+      },
+      "subject_id": {
+        "description": "Discord member or role ID",
+        "pattern": "^\\d{17,20}$",
+        "type": "string"
+      },
+      "subject_timed_out": {
+        "type": "boolean"
+      },
+      "subject_type": {
+        "enum": [
+          "member",
+          "role"
+        ],
+        "type": "string"
+      },
+      "unknown_permission_bits": {
+        "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR).",
+        "pattern": "^\\d+$",
+        "type": "string"
+      },
+      "warnings": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "guild_id",
+      "channel_id",
+      "permission_source_channel_id",
+      "subject_type",
+      "subject_id",
+      "action",
+      "requested_permissions",
+      "allowed",
+      "base_permissions",
+      "effective_permissions",
+      "unknown_permission_bits",
+      "missing_permissions",
+      "ineffective_permissions",
+      "implicit_denies",
+      "administrator",
+      "guild_owner",
+      "subject_timed_out",
+      "applied_role_ids",
+      "decision_trace",
+      "role_hierarchy_check",
+      "warnings",
+      "confidence"
+    ],
+    "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.5/5.0

Behavior5/5

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

Annotations already establish read-only/idempotent behavior, and the description adds valuable nuance: 'allowed:null means Discord did not expose enough evidence for a safe conclusion.' This clarifies the open-world nature and warns against treating inconclusive results as permission, which is essential behavioral context beyond the base annotations.

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 tightly structured with bolded headers (Purpose, When to use, When NOT to use, Returns) and each section is a single, information-dense line. It is front-loaded with the core purpose and avoids any filler.

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?

Given the rich input schema, output schema, and annotations, the description covers all the additional context an agent needs: when to call it, what it returns, and how to interpret the critical nullable 'allowed' field. No missing information that would prevent correct invocation.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents each parameter thoroughly, including mutual exclusivity and required conditions for channel actions. The tool description does not add meaning beyond that baseline, which is exactly the expected level when schema carries the burden.

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, actionable purpose: 'Explain effective Discord permissions for one guild member or one role.' This clearly identifies the verb, resource, and scope. It also differentiates from siblings like permissions_audit_channel by focusing on member/role evaluation rather than channel-level audits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'When to use' and 'When NOT to use' sections give explicit conditions: verify before a write, diagnose allow/deny, and avoid mutations or treating partial results as permission. However, it does not name specific alternative sibling tools, so the guidance is strong but not fully complete.

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

Deploy Server