discord-mcp

discord_search_members

Read-onlyIdempotent

Find Discord server members whose username or nickname starts with a given prefix, returning user IDs, roles, and join dates without requiring the privileged Server Members intent.

Instructions

Find server members whose username or nickname starts with a string.

The quickest way to turn a name into a user_id. Does not need the privileged
Server Members intent (unlike discord_list_members).

Returns: Markdown table (member, roles, joined) or JSON list of {user_id, username,
display_name, nick, bot, roles, joined_at, timed_out_until}.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes	Username or nickname prefix, e.g. 'jam' finds 'James'.
`guild_id`	No	Server (guild) ID. Omit to use DISCORD_GUILD_ID from .env.
`response_format`	No	'markdown' for reading, 'json' for full structured data.	markdown

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 3, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, open-world and non-destructive traits. The description adds genuinely useful behavioral context beyond that: the privileged-intent requirement difference versus discord_list_members and the two possible response shapes. Auth/permission details and search behavior on multiple matches are not covered, so it stops short of 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.

Conciseness5/5

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

Three short blocks: what it does, why it beats the alternative, what comes back. Scoping and the routing hint are front-loaded, and every sentence carries information.

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?

Covers purpose, alternative, intent caveat and return shape for a 4-param read tool with a structured schema and output schema. Some return-value detail is duplicated rather than additive, and it omits behavior when several members match or when nothing matches, keeping it from a 5.

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 coverage is 75% and the schema itself supplies the prefix example for 'query' and the guild_id env fallback. The description adds return-field names but no syntax or constraint detail for limit, query or guild_id, so the 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 precise verb+resource+scope: prefix search over username or nickname. It explicitly distinguishes itself from the sibling discord_list_members, so an agent can route between them without opening schemas.

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 the when-to-use framing ('quickest way to turn a name into a user_id') and names the alternative (discord_list_members) along with the deciding condition (no privileged Server Members intent required). 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.