discord-mcp

permissions_audit_channel

Read-onlyIdempotent

Audit guild role baselines for a channel or thread: view, send, or manage. Identify allowed, denied, and unknown permissions per role to plan permission changes.

Instructions

Purpose: Audit which individual guild roles can view, send in, or manage one channel or thread. Each role is evaluated independently with @everyone; member-specific overwrites and multi-role combinations are intentionally excluded. Thread management uses MANAGE_THREADS.

When to use:

Review channel exposure before redesigning roles or permission overwrites.
Find role baselines that allow, deny, or cannot prove channel access.

When NOT to use:

Determining one member's effective access; use permissions_explain for that member.
Predicting whether a locked or archived thread operation will succeed right now; this audits permission baselines, not mutable thread state.
Mutating roles or overwrites; this tool is read-only.

Returns: a compact per-role action matrix plus allowed, denied, and unknown counts. Omit actions to audit all three actions; select fewer actions to reduce output.

Input Schema

TableJSON Schema

Name	Required	Description
`actions`	No	Optional action subset; defaults to view_channel, send_messages, manage_channel
`guild_id`	Yes	Guild whose roles should be audited
`channel_id`	Yes	Guild channel or thread whose role baselines should be audited

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": {
-      "channel_id": {
-        "description": "Discord channel ID (snowflake)",
-        "pattern": "^\\d{17,20}$",
-        "type": "string"
-      },
-      "confidence": {
-        "enum": [
-          "complete",
-          "partial"
-        ],
-        "type": "string"
-      },
-      "guild_id": {
-        "description": "Discord guild (server) ID",
-        "pattern": "^\\d{17,20}$",
-        "type": "string"
-      },
-      "member_overwrite_count": {
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "permission_source_channel_id": {
-        "anyOf": [
-          {
-            "description": "Discord channel ID (snowflake)",
-            "pattern": "^\\d{17,20}$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "requested_actions": {
-        "items": {
-          "enum": [
-            "view_channel",
-            "send_messages",
-            "manage_channel"
-          ],
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "roles": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "actions": {
-              "additionalProperties": false,
-              "properties": {
-                "manage_channel": {
-                  "anyOf": [
-                    {
-                      "type": "boolean"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                },
-                "send_messages": {
-                  "anyOf": [
-                    {
-                      "type": "boolean"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                },
-                "view_channel": {
-                  "anyOf": [
-                    {
-                      "type": "boolean"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                }
-              },
-              "type": "object"
-            },
-            "administrator": {
-              "type": "boolean"
-            },
-            "id": {
-              "description": "Discord role ID",
-              "pattern": "^\\d{17,20}$",
-              "type": "string"
-            },
-            "managed": {
-              "type": "boolean"
-            },
-            "name": {
-              "type": "string"
-            },
-            "position": {
-              "maximum": 9007199254740991,
-              "minimum": -9007199254740991,
-              "type": "integer"
-            }
-          },
-          "required": [
-            "id",
-            "name",
-            "position",
-            "managed",
-            "administrator",
-            "actions"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "summary": {
-        "additionalProperties": false,
-        "properties": {
-          "by_action": {
-            "additionalProperties": false,
-            "properties": {
-              "manage_channel": {
-                "additionalProperties": false,
-                "properties": {
-                  "allowed": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  },
-                  "denied": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  },
-                  "unknown": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  }
-                },
-                "required": [
-                  "allowed",
-                  "denied",
-                  "unknown"
-                ],
-                "type": "object"
-              },
-              "send_messages": {
-                "additionalProperties": false,
-                "properties": {
-                  "allowed": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  },
-                  "denied": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  },
-                  "unknown": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  }
-                },
-                "required": [
-                  "allowed",
-                  "denied",
-                  "unknown"
-                ],
-                "type": "object"
-              },
-              "view_channel": {
-                "additionalProperties": false,
-                "properties": {
-                  "allowed": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  },
-                  "denied": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  },
-                  "unknown": {
-                    "maximum": 9007199254740991,
-                    "minimum": 0,
-                    "type": "integer"
-                  }
-                },
-                "required": [
-                  "allowed",
-                  "denied",
-                  "unknown"
-                ],
-                "type": "object"
-              }
-            },
-            "type": "object"
-          },
-          "role_count": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "role_count",
-          "by_action"
-        ],
-        "type": "object"
-      },
-      "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",
-      "requested_actions",
-      "roles",
-      "summary",
-      "member_overwrite_count",
-      "unknown_permission_bits",
-      "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": {
+      "channel_id": {
+        "description": "Discord channel ID (snowflake)",
+        "pattern": "^\\d{17,20}$",
+        "type": "string"
+      },
+      "confidence": {
+        "enum": [
+          "complete",
+          "partial"
+        ],
+        "type": "string"
+      },
+      "guild_id": {
+        "description": "Discord guild (server) ID",
+        "pattern": "^\\d{17,20}$",
+        "type": "string"
+      },
+      "member_overwrite_count": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "permission_source_channel_id": {
+        "anyOf": [
+          {
+            "description": "Discord channel ID (snowflake)",
+            "pattern": "^\\d{17,20}$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "requested_actions": {
+        "items": {
+          "enum": [
+            "view_channel",
+            "send_messages",
+            "manage_channel"
+          ],
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "roles": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "actions": {
+              "additionalProperties": false,
+              "properties": {
+                "manage_channel": {
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "send_messages": {
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "view_channel": {
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                }
+              },
+              "type": "object"
+            },
+            "administrator": {
+              "type": "boolean"
+            },
+            "id": {
+              "description": "Discord role ID",
+              "pattern": "^\\d{17,20}$",
+              "type": "string"
+            },
+            "managed": {
+              "type": "boolean"
+            },
+            "name": {
+              "type": "string"
+            },
+            "position": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "position",
+            "managed",
+            "administrator",
+            "actions"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "summary": {
+        "additionalProperties": false,
+        "properties": {
+          "by_action": {
+            "additionalProperties": false,
+            "properties": {
+              "manage_channel": {
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "denied": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "unknown": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "allowed",
+                  "denied",
+                  "unknown"
+                ],
+                "type": "object"
+              },
+              "send_messages": {
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "denied": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "unknown": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "allowed",
+                  "denied",
+                  "unknown"
+                ],
+                "type": "object"
+              },
+              "view_channel": {
+                "additionalProperties": false,
+                "properties": {
+                  "allowed": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "denied": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "unknown": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "allowed",
+                  "denied",
+                  "unknown"
+                ],
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "role_count": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "role_count",
+          "by_action"
+        ],
+        "type": "object"
+      },
+      "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",
+      "requested_actions",
+      "roles",
+      "summary",
+      "member_overwrite_count",
+      "unknown_permission_bits",
+      "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.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it evaluates each role independently with @everyone, intentionally excludes member-specific overwrites and multi-role combinations, and uses MANAGE_THREADS for thread management. It also clarifies that it audits permission baselines, not mutable thread state, which prevents misuse. No contradiction with 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 well-structured with bold section headers (Purpose, When to use, When NOT to use, Returns) and is front-loaded with the core purpose. Each sentence earns its place: the purpose is concise, usage guidance is actionable, exclusions are clear, and return format is summarized. While longer than average, it is efficiently organized for a tool with this complexity, and no wasted words are present.

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?

The description covers all necessary context: what the tool does, when to use it, when not to, what it returns (per-role action matrix with counts), and how to control output via the actions parameter. It also mentions thread-specific behavior (MANAGE_THREADS) and the exclusion of mutable state. Given that an output schema exists, the description does not need to explain return values in detail, but it gives a high-level summary sufficient for an agent to decide whether to call it. It is complete for a tool of this complexity.

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 baseline is 3. The description adds extra clarity by explaining the actions parameter's effect: 'Omit actions to audit all three actions; select fewer actions to reduce output.' This goes beyond the schema's default list, helping the agent understand the practical impact of choosing a subset. The description also reinforces the meaning of guild_id and channel_id without redundancy.

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 precise statement of the tool's function: auditing which individual guild roles can view, send in, or manage one channel or thread. It names the specific actions (view_channel, send_messages, manage_channel) and clarifies the scope (individual roles, independent evaluation with @everyone). This clearly distinguishes it from siblings like permissions_explain, which handles member-specific access.

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 includes explicit 'When to use' and 'When NOT to use' sections, providing concrete scenarios for when this tool is appropriate (reviewing channel exposure, finding role baselines) and when to use alternatives (permissions_explain for member effective access, and noting it's not for mutable thread state or mutations). It names the specific alternative tool, making routing unambiguous.

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

Deploy Server