Discord MCP - Discord server management MCP for AI agents

Remove role

remove_role

Remove a Discord role from a member with hierarchy preflight and a preview/confirm-token step that prevents unintended access changes.

Instructions

Take a role away from a member. Preflights the bot's role hierarchy so a failure is an explanation, not a 403. Usually done at once. A role can also hold someone back (one that hides channels from whoever has it, such as a quarantine role); taking that away lets them in, so it needs confirming: the first call changes nothing and returns a preview and a confirm_token, and repeating the call with the token makes the change.

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": {
      "member": "<member>",
      "role": "<role>"
    },
    "name": "remove_role"
  }
}

Input Schema

Name	Required	Description
`role`	Yes	Role name or ID.
`guild`	No	Guild (server) name or ID. Omit to use the default guild.
`member`	Yes	Member name or user ID.
`reason`	No
`dry_run`	No
`confirm_token`	No	The token from this exact action's preview. Where the app can show a confirmation dialog, calling with it asks the user there, and it happens only if they agree.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.4.2Nov 12, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / properties / confirm_token

Added value: +{
+  "description": "The token from this exact action's preview. Where the app can show a confirmation dialog, calling with it asks the user there, and it happens only if they agree.",
+  "type": "string"
+}

addedInput schema / properties / dry_run
```
Added value: +{
+  "type": "boolean"
+}
```

Changed1 schema field changedv1.3.0Aug 12, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
First observedv1.0.2Jun 14, 2026

TDQS

A4.6/5.0

Behavior5/5

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

It discloses behavior well beyond the annotations: a preflight hierarchy check that converts a 403 into an explanatory failure, and the crucial non-obvious side effect that removing a restricting role grants access rather than revoking it. The exact mechanics of the confirm cycle (first call changes nothing and returns a preview plus confirm_token; repeating with the token applies it) are spelled out. Nothing here contradicts readOnlyHint=false or destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and every sentence carries content, including the justification for the confirmation gate. The long parenthetical about quarantine roles is dense and slightly tangled, and the phrase 'Usually done at once' is vague enough to need a second reading.

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?

For a six-parameter mutation with no output schema and thin annotations, the description covers the safety profile, the side-effect risk, and the full two-phase invocation protocol. The remaining gaps (dry_run, reason, preview payload shape) are secondary and partly handled by the schema itself.

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 67%, so the baseline sits near 3, but the description meaningfully explains the confirm_token contract that the schema only sketches: the token must come from this exact action's preview and the change happens only after confirmation. It says nothing about dry_run or reason, both of which lack schema descriptions, and does not clarify how dry_run interacts with the preview/confirm flow.

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?

Opening sentence gives a specific verb and resource: 'Take a role away from a member.' This is unambiguously the inverse of assign_role and cannot be confused with sibling mutators like create_role, update_role, or delete_role, which act on the role itself rather than on a member-role pairing.

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?

It states the normal case ('Usually done at once') and the exception that forces a two-step flow: roles that gate channel visibility, such as a quarantine role. That is concrete when-to-use guidance for the confirmation path. It stops short of naming assign_role as the counterpart operation or stating prerequisites like needing Manage Roles, so it is clear context rather than full routing guidance.

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

Deploy Server