discord-mcp

members_bulk_add_role

Idempotent

Assign one Discord role to 1-100 known guild members in a single batch and return succeeded/failed user IDs; retries are safe because writes are idempotent.

Instructions

Purpose: Add one role to 1-100 explicitly identified guild members.

When to use:

Assign the same existing role to a bounded list of known members.

When NOT to use:

Assigning a role to one member -> use members_add_role.
Discovering or filtering members -> use members_list first.

Returns: {role_id, succeeded_user_ids, failed_user_ids, succeeded_count, failed_count}. Each successful PUT includes an idempotent no-op when the member already has the role. An unknown member is reported as a per-member failure. Permission, rate-limit, upstream, and other infrastructure errors stop the batch; prior successful writes remain, and retrying the same request is safe because each PUT is idempotent.

Input Schema

Name	Required	Description
`role_id`	Yes	Role to add
`guild_id`	Yes	Guild containing the members
`user_ids`	Yes	Unique member IDs to grant the role to (1-100)
`audit_reason`	No	Reason recorded in audit log (X-Audit-Log-Reason header)

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.32.0Oct 15, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is partly covered. The description goes further, disclosing partial-failure semantics (unknown members reported per-member; infrastructure errors abort the batch while prior writes persist) and retry safety, which the annotations do not convey. The idempotency note partly restates the annotation, keeping this from a 5.

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?

Well-structured with labeled sections and front-loaded purpose and routing rules. The 'Returns' paragraph is somewhat redundant since an output schema exists, but the failure-mode detail it carries is behavioral rather than mere return-shape restatement, so the extra length is mostly earned.

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 bounded write tool with annotations and an output schema, this covers everything an agent needs: scope limits, sibling routing, failure isolation, idempotent retry behavior, and the audit-reason parameter's purpose. No material gap remains.

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% and all four parameters are documented in the schema, so the schema carries the load. The description reinforces the 1-100 bound and the per-member identifier scope but adds no format, syntax, or validation detail beyond the schema. Baseline 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+resource+scope ('Add one role to 1-100 explicitly identified guild members'), which immediately distinguishes it from the single-member `members_add_role` and the discovery-oriented `members_list` sibling. An agent can select this tool without opening either 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?

Explicit 'When to use' and 'When NOT to use' sections name the two alternatives (`members_add_role` for single members, `members_list` for discovery/filtering) with the exact condition that routes to each. Nothing is left to inference.

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

Deploy Server