discord-mcp

discord_create_role

Create a new Discord server role with a specified name, color, permissions, and display settings, returning its ID for assigning members.

Instructions

Create a new role in a server. Requires the Manage Roles permission; the new role is placed below the bot's highest role. Use discord_add_role to then assign it to members. Returns the new role's name and ID. To change an existing role, use discord_edit_role.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "guild_id": "<guild_id>",
      "name": "<name>"
    },
    "name": "discord_create_role"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	Name of the new role (max 100 characters).
`color`	No	Role color as a hex string, e.g. '#FF5733'.
`hoist`	No	If true, display members with this role separately in the member list.
`guild_id`	Yes	Discord server (guild) ID (snowflake).
`mentionable`	No	If true, anyone can @mention this role.
`permissions`	No	Server-wide permission flag names to grant, e.g. ['SendMessages','ViewChannel']. Uses Discord PermissionsBitField flag names.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.2.0Sep 6, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
Changed5 schema fields changedv2.0.0Jun 27, 2026
- addedInput schema / properties / color / pattern
```
Added value: +"^#[0-9A-Fa-f]{6}$"
```
- addedInput schema / properties / guild_id / pattern
```
Added value: +"^\\d{17,20}$"
```
- addedInput schema / properties / permissions / anyOf
```
Added value: +[
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  {
+    "type": "string"
+  }
+]
```
- removedInput schema / properties / permissions / items
```
Removed value: -{
-  "type": "string"
-}
```
- removedInput schema / properties / permissions / type
```
Removed value: -"array"
```

Changed6 schema fields changedv1.6.0May 28, 2026

changedInput schema / properties / color / description

Previous value: -"Hex color e.g. #FF5733"New value: +"Role color as a hex string, e.g. '#FF5733'."

addedInput schema / properties / guild_id / description

Added value: +"Discord server (guild) ID (snowflake)."

addedInput schema / properties / hoist / description

Added value: +"If true, display members with this role separately in the member list."

addedInput schema / properties / mentionable / description

Added value: +"If true, anyone can @mention this role."

addedInput schema / properties / name / description

Added value: +"Name of the new role (max 100 characters)."

changedInput schema / properties / permissions / description

Previous value: -"e.g. ['SendMessages','ViewChannel']"New value: +"Server-wide permission flag names to grant, e.g. ['SendMessages','ViewChannel']. Uses Discord PermissionsBitField flag names."

Addedv1.5.0May 8, 2026
Removedv1.0.0May 1, 2026
First observedv0.1.0Mar 21, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already flag a non-readonly, non-idempotent, non-destructive open-world write, so the safety profile is covered. The description adds genuinely new behavior: the Manage Roles authorization requirement, the hierarchy constraint that the new role lands below the bot's highest role, and what is returned. Only rate limits or duplicate-name handling are absent.

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?

Four short sentences, front-loaded with the action, then permission/placement constraint, then the next-step pointer, then the alternative. No filler and no repetition of the name.

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 six-parameter mutation tool with no output schema, the description covers purpose, permission gate, placement side effect, return value, and adjacent operations. Remaining gaps (failure modes, whether partial matches on role names matter) are minor.

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%, with each parameter including format hints such as the hex color pattern and PermissionsBitField flag names. The description adds nothing about individual parameters, so the baseline of 3 applies.

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?

States a specific verb and resource ("Create a new role in a server") and immediately separates itself from discord_edit_role (changing existing) and discord_add_role (assigning). An agent can pick the right tool without opening the schema.

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?

Gives both the follow-up step ("Use discord_add_role to then assign it to members") and an explicit exclusion routing to discord_edit_role for existing roles, plus the required Manage Roles permission as a precondition.

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

Deploy Server