create_role
Creates a Discord role with customizable name, color, permissions, and hierarchical placement above or below other roles.
Instructions
Creates a role. IMPORTANT: Discord positions are inverted — higher number = higher/more powerful, @everyone = 0 at the bottom, and a new role defaults to the BOTTOM. To make an important role rank high, pass placement:"top" (or "above"/"below" a reference role). Do not rely on raw position numbers unless you know Discord's inverted scheme.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the role (1-100 characters) | |
| color | No | Role color as hex string (#FF0000) or integer (0-16777215) | |
| hoist | No | Display members with this role separately in the sidebar | |
| guildId | No | Guild ID or name. Defaults to the currently selected guild. | |
| position | No | Raw Discord position (higher = more powerful). Overrides placement. Prefer placement instead. | |
| placement | No | Where to rank the role. "top" = highest the bot can assign (just under the bot), "bottom" = just above @everyone (Discord default), "above"/"below" = relative to referenceRoleId. Prefer this over raw position. | |
| mentionable | No | Allow anyone to @mention this role | |
| permissions | No | Array of Discord permission names in SCREAMING_SNAKE_CASE (e.g. VIEW_CHANNEL, SEND_MESSAGES, MANAGE_ROLES, KICK_MEMBERS, ADMINISTRATOR, USE_VAD, SEND_TTS_MESSAGES). Unknown names are rejected rather than silently ignored. | |
| referenceRoleId | No | Role ID to place the new role above/below (required when placement is "above" or "below"). |