Skip to main content
Glama
cappyeo

discord-mcp

by cappyeo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

events_list

Read-onlyIdempotent

List scheduled events for a Discord guild, including voice, stage, and external events. Retrieves upcoming events and returns a count.

Instructions

Purpose: List scheduled events for a guild.

When to use: enumerate upcoming voice/stage/external events.

Returns: {events:[...], count}. Structured names and descriptions remain raw Discord data; the human-readable text response fences event names.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
guild_idYesGuild to query

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.28.0
    • changedOutput schema / anyOf
      Previous value: -[
-  {
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "additionalProperties": {},
-    "properties": {
-      "count": {
-        "type": "number"
-      },
-      "events": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "channel_id": {
-              "anyOf": [
-                {
-                  "description": "Discord channel ID (snowflake)",
-                  "pattern": "^\\d{17,20}$",
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "creator_id": {
-              "anyOf": [
-                {
-                  "description": "Discord user ID",
-                  "pattern": "^\\d{17,20}$",
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "description": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "entity_type": {
-              "maximum": 9007199254740991,
-              "minimum": -9007199254740991,
-              "type": "integer"
-            },
-            "id": {
-              "type": "string"
-            },
-            "name": {
-              "type": "string"
-            },
-            "scheduled_end_time": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "scheduled_start_time": {
-              "type": "string"
-            },
-            "status": {
-              "maximum": 9007199254740991,
-              "minimum": -9007199254740991,
-              "type": "integer"
-            }
-          },
-          "required": [
-            "id",
-            "name",
-            "scheduled_start_time",
-            "scheduled_end_time",
-            "status",
-            "entity_type",
-            "channel_id"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "events",
-      "count"
-    ],
-    "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": {
+      "count": {
+        "type": "number"
+      },
+      "events": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "channel_id": {
+              "anyOf": [
+                {
+                  "description": "Discord channel ID (snowflake)",
+                  "pattern": "^\\d{17,20}$",
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "creator_id": {
+              "anyOf": [
+                {
+                  "description": "Discord user ID",
+                  "pattern": "^\\d{17,20}$",
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "description": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "entity_type": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "scheduled_end_time": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "scheduled_start_time": {
+              "type": "string"
+            },
+            "status": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "scheduled_start_time",
+            "scheduled_end_time",
+            "status",
+            "entity_type",
+            "channel_id"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "events",
+      "count"
+    ],
+    "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"
+  }
+]
  2. First observedv0.22.0

TDQS

A4/5.0
Behavior4/5

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

The annotations already cover the read-only, idempotent, non-destructive nature of the tool. The description adds extra behavioral value by stating the return shape and warning that structured event names and descriptions contain raw Discord data while the human-readable response fences event names, which is useful and not redundant.

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 uses three short labeled sections: purpose, when-to-use, and return behavior. The core purpose is front-loaded, and each sentence contributes useful information without padding or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with full schema coverage, a descriptive output schema, and rich annotations, the description is largely complete. It explains the purpose, the intended use case, and the return behavior. Minor omissions like pagination or sort order are not critical for safe invocation but would make it even stronger.

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?

The only parameter, guild_id, has complete schema documentation with type, pattern, and description, so schema coverage is 100%. The tool description does not add any further semantic detail about the parameter, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List scheduled events for a guild') and clarifies the scope ('upcoming voice/stage/external events'). It is clear enough to be distinguished from mutation tools like events_create and from events_get, but it does not explicitly name sibling alternatives, so it stops short of full differentiation.

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?

There is a clear 'When to use' section indicating this tool is for enumerating upcoming voice/stage/external events. It gives the caller the relevant context, but it does not explicitly mention when to use a different tool instead, such as events_get or events_list_users.

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

Deploy Server

Other Tools