This server exposes a fixed catalog of Discord actions centered on messaging, reactions, attachments, channels/DMs, friends, and presence.
Send, edit, and delete messages, including replies, TTS, and up to 10 file attachments.
Add or remove reactions on messages.
Read message history, search messages with filters, fetch a single message, and list attachments.
Download Discord attachments and clean up downloaded files.
Get channel details, list DM channels, and create or retrieve a DM with a user.
List friends and send or remove friend requests.
Update or clear presence and activity/status.
Provides comprehensive Discord bot management capabilities including server information, channel creation and management, message operations, role and permission management, member moderation, voice channel operations, webhook management, and audit logging through Discord's API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Discord MCP Server create a new text channel named announcements in the general category"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The model discovers the live discord.js API, writes its own helpers, and keeps them across calls and restarts, instead of picking from a fixed menu of verbs.
Quick start · The run tool · Secrets · Other MCP servers · Configuration · Security
▶ Watch the teaser with sound
The one tool this server exposes runs JavaScript with the server's full authority: the network, the filesystem, the process. That is the design, not a mode, and there is no switch to turn it off. Run the server sandboxed (a container, VM or jail with only the access you intend to grant), and keep Discord tokens out of it with discord-mcp agent: then the code can use Discord but can never read a token.
A fixed catalog of typed tools is the wrong interface for Discord. Every bot, permission set and library version supports a different slice of the API, and different models are good with different tools. So this server doesn't hand-pick verbs. It exposes a single tool, run, gives the code a live discord.js client, and lets each deployment's model build the tooling it needs.
// call 1: the model writes a helper...
async function channelByName(guildId, name) {
const guild = await client.guilds.fetch(guildId);
return (await guild.channels.fetch()).find((c) => c.name === name);
}
// call 2 (or next week, after a restart): ...and reuses it
const general = await channelByName("123456789012345678", "general");
await general.send(vars.announcement);Highlights
One tool, the whole API. client is a real discord.js Client. describe(x) shows live state and every method's signature and doc, so the model can find its way.
It remembers. Functions, classes and constants the model defines are saved and reloaded on restart. Side effects never are.
Tokens stay out of reach. An ssh-agent-style agent holds the tokens, so the server and the model only ever see agent:<id>.
Other MCP servers become functions. mcp.github.get_issue(...) inside the same code, not a growing list of tools.
Hardened networking. Optional proxy for all Discord traffic, https-only upstreams with known_hosts pinning, per-identity latency, and tokens kept out of logs and traces.
Related MCP server: discord-mcp
flowchart LR
M["Model<br>(any MCP client)"] -- "run(code)" --> S
subgraph S["discord-mcp server"]
direction TB
N["Persistent JS namespace<br>client · describe · ops · kept helpers"]
U["mcp.server.tool()"]
end
N -- "agent:id placeholder<br>(Unix socket)" --> A["discord-mcp agent<br>holds the decrypted tokens"]
A -- "real token<br>REST + gateway" --> D[("Discord")]
U --> O["Other MCP servers<br>https or stdio"]Prerequisites: Node.js 22.15+, npm, and a Discord bot token.
git clone https://github.com/drvova/discord-mcp.git
cd discord-mcp
npm install # also builds dist/1. Store the token, encrypted, like an SSH key. You're prompted (hidden) for the token and a passphrase.
node dist/bootstrap.js identity add default-bot2. Start the agent in its own terminal, like ssh-agent. It asks for the passphrase and prints the socket to use.
node dist/bootstrap.js agent
# DISCORD_MCP_AGENT_SOCK=/run/user/1000/discord-mcp/agent.sock; export DISCORD_MCP_AGENT_SOCK;3. Point your MCP client at the server, with only the agent socket in its environment:
{
"mcpServers": {
"discord": {
"command": "node",
"args": ["/absolute/path/to/discord-mcp/dist/bootstrap.js"],
"env": { "DISCORD_MCP_AGENT_SOCK": "/run/user/1000/discord-mcp/agent.sock" }
}
}
}Then ask the model to call run with empty code: it gets the manual and takes it from there.
Skip the agent and give the server the token directly:
DISCORD_TOKEN=your_bot_token node dist/bootstrap.jsThis works, but the token then lives in the server process, where code in the run tool can read it (for example through the client's auth config). The server warns about this at startup. Secret environment variables are removed from process.env once read, in both modes.
Command | What it does |
| stdio server (the default MCP transport) |
| HTTP + SSE server on port 1455 (see HTTP mode) |
| rebuild on change and restart, with pretty logs |
| containerised server; mount a volume at |
run is the only tool the server advertises.
Argument | Type | |
| string, required | JavaScript to run. Empty returns the manual. |
| string | Identity to bind as |
| object of strings | Named strings available as |
The code runs in one long-lived namespace with top-level await. The result is whatever it printed plus the value of its last expression.
Name | What it is |
| The bound discord.js |
| List and switch identities; |
|
|
| Live capabilities (for a client: ready, user, intents, guilds, REST latency) and every member's signature with a one-line doc from discord.js's JSDoc |
| The loaded Discord packages, their symbols and exports, and the discord.js module |
| Structured operations with dry runs and preflight checks, as plain functions |
| Other MCP servers as functions |
| Proxy and TLS policy, latency per identity and server, gateway ping |
| Saved definitions |
| I/O and utilities |
Each block is the code of one run call.
// What can this bot do right now?
describe(client)// Search what discord.js exports
(await symbols("TextChannel#send")).items.map((s) => s.name)// Check a call before making it
await ops.preflight({
packageAlias: "discordjs",
symbol: "TextChannel#send",
kind: "function",
target: "channel",
context: { channelId: "123456789012345678" },
})// Switch to another identity the agent holds
await bind("ops-bot");
client.user.tagAfter each successful call, every top-level definition (a function or class declaration, or a const bound to a literal, function or class) is saved as its own file and loaded back when the server starts. Each one loads in isolation, so a broken file is reported by kept() and never stops the server. Statements that do work (calls, let, const x = await …) are never saved or replayed.
Definitions live in DISCORD_MCP_KEPT_DIR (default ~/.config/discord-mcp/kept). In a container, mount it as a volume.
Discord tokens are handled the way SSH handles private keys.
SSH | discord-mcp |
|
|
|
|
|
|
the agent signs; the key never leaves it | the agent puts the token on Discord requests; the server only holds |
"UNPROTECTED PRIVATE KEY FILE!" | secret files readable by others are refused, with the |
|
|
REST. The server's discord.js client logs in as agent:default-bot and sends its REST requests to the agent over the Unix socket. The agent swaps the placeholder Authorization header for the real token and forwards the request to https://discord.com/api, always to that base, whatever path the client sends.
Gateway. The gateway URL Discord returns is replaced with an agent address. The agent relays the WebSocket and swaps the token inside the IDENTIFY and RESUME frames. It only connects to gateway URLs Discord itself returned, which clients see as opaque handles, and only on wss://*.discord.gg.
The result. Code in run can use Discord (client, ops.*, its own helpers) but can't read a token. It isn't in client.token, the auth config, process.env, the encrypted file, or the agent's API. connect() is disabled with the agent, so tokens never pass through the model.
Adding identities. identity add encrypts into the file and, when DISCORD_MCP_AGENT_SOCK is set, also loads the identity into the running agent, like ssh-add; then bind("id").
Input. Tokens and passphrases come from a hidden prompt, a mode 600 file (--token-file, DISCORD_MCP_PASSPHRASE_FILE) or stdin, never from command-line arguments (visible in ps). --token-env DISCORD_TOKEN migrates an existing variable.
Unattended agents (containers, services): set DISCORD_MCP_PASSPHRASE_FILE to a mode 600 file. For a Docker secret, give it mode: 0400.
Proxy. With DISCORD_MCP_PROXY set, the agent sends REST and the gateway through it.
Threat model. Like ssh-agent, this protects tokens from code running in the server, not from other processes running as the same OS user with debugging rights. Start the agent separately (not as the server's child). For a hard boundary, run it as a different OS user or in its own container, sharing only the socket. Anything that can reach the socket can use the identities, exactly like SSH agent forwarding.
Other MCP servers aren't re-advertised as tools. Their tools become async functions in the namespace (the "code mode" pattern), so the model composes several calls in one run, filters results in code, and prints only what it needs:
// GitHub issues mentioned in the last 50 messages of a channel
const channel = await client.channels.fetch("123456789012345678");
const refs = [...(await channel.messages.fetch({ limit: 50 })).values()]
.flatMap((m) => [...m.content.matchAll(/#(\d+)/g)].map((x) => Number(x[1])));
for (const n of new Set(refs)) {
const issue = await mcp.github.get_issue({ owner: "acme", repo: "app", issue_number: n });
print(`#${n} ${issue.state} ${issue.title}`);
}Results: a call resolves to the tool's structured content, or its text (parsed when it's JSON). A tool error is thrown.
Discovery: tool names become identifiers (get-issue → get_issue). describe(mcp.github) lists each tool's signature, generated from its input schema.
Configuration: servers in DISCORD_MCP_UPSTREAMS (inline JSON or a file, in the usual mcpServers shape) connect at startup. ${VAR} is read from the environment, so secrets stay out of the file:
{
"mcpServers": {
"github": { "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } },
"files": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }
}
}Transports: url servers use streamable HTTP with SSE fallback (force one with "type": "http" or "sse"). command servers use stdio. An unreachable server shows up in mcpServers() and doesn't stop startup.
At runtime: mcpConnect(name, config) adds a server until the next restart. Helpers that wrap mcp.* calls are saved like any other definition.
Proxy |
|
Not proxied | In direct mode, the Discord gateway WebSocket ( |
Encrypted upstreams | Upstream MCP URLs must be |
known_hosts | Upstream servers and an https proxy are pinned by the SHA-256 of their TLS public key on first use. A changed key is refused ("REMOTE HOST IDENTIFICATION HAS CHANGED"); clear it with |
Latency | Discord REST is timed per identity and upstream calls per server (count, errors, last, avg, p50, p95), shown in |
No tokens in telemetry | Latency is labelled by identity or server name, never by token. Trace spans have Discord webhook and interaction tokens removed from paths ( |
Environment variables, all optional. A .env file in the working directory is loaded too.
Variable | |
| The agent socket. Recommended: then the server needs no token at all |
| Direct mode only |
| Default guild |
| Comma-separated gateway intents (privileged ones must be enabled in the Developer Portal) |
| Where |
| Override those two paths individually |
| Mode 600 file with the identities passphrase, for unattended agents |
| Legacy direct-mode store for |
Variable | |
| Saved definitions (default |
| Other MCP servers: inline JSON or a path, |
|
|
|
|
|
|
| Append every |
Variable | |
|
|
|
|
| Colors on/off; |
| OpenTelemetry (on by default; |
| Where traces go (OTLP over HTTP) |
| Prometheus metrics (default |
| Serve over HTTP + SSE instead of stdio |
| OAuth bot-install flow in HTTP mode |
With MCP_HTTP_PORT set, the server speaks MCP over HTTP and SSE:
Endpoint | |
| MCP JSON-RPC: |
| MCP over SSE |
| Health check |
| OAuth bot install |
A typed client is generated from the route types:
import { createHttpClient } from "./src/http-client.js";
const client = createHttpClient("http://localhost:1455");
const health = await (await client.health.$get()).json();Sandbox the server. run executes code with the server's full authority. Give the container, VM or jail only the network, filesystem and identities you intend the model to use.
Use the agent. It keeps tokens out of the server process. In direct mode, run code can read them.
Least privilege on Discord. Give bots only the permissions they need, and rotate tokens.
Audit. Every run call is written to the audit log; set DISCORD_MCP_AUDIT_LOG_PATH in production.
Know what the policy covers. DISCORD_MCP_BLOCK_HIGH_RISK, dryRun and allowWrite apply to ops.* only. Code that uses client directly is bounded by the sandbox and the bot's Discord permissions.
The toolchain is Rstack: Rslib builds, Rstest tests, Rslint lints and type-checks.
Script | |
| Build |
| Build, then rebuild and restart on change, with pretty logs |
| Build, then run the Rstest suite (some tests spawn the built server) |
| Rslint: lint, type-check (TypeScript's native compiler), or both |
The animated banner and the teaser trailer are authored with Clayzo in assets/banner, its own small project; the trailer's soundtrack is synthesised by a Python script there, and its player page lives in site.
The default branch is new-architecture-main.
Send a friend request to a user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't cover critical aspects like required permissions, rate limits, response format, or whether the request is reversible. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action, making it easy to parse quickly without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., auth needs, error handling) and doesn't explain what the tool returns, leaving the agent with insufficient context for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add param details, but this is acceptable given the schema's completeness, warranting a baseline score above minimum viable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Send a friend request') and the target ('to a user'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'discord_remove_friend' or 'discord_get_friends', which would require explicit comparison for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites (e.g., needing a user ID), exclusions, or comparisons to siblings like 'discord_remove_friend' for friend management or 'discord_create_dm' for initiating communication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a reaction to a message
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| messageId | Yes | The message ID to react to | |
| emoji | Yes | Emoji to react with (Unicode or custom emoji format) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Add a reaction' implies a write operation, it doesn't specify whether this requires specific permissions, if there are rate limits, what happens if the emoji is invalid, or what the typical response looks like. The description is minimal and lacks important behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 5 words, front-loading the core purpose with zero wasted words. Every word earns its place, making it efficient for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after the reaction is added, what errors might occur, or any behavioral nuances. Given the complexity of Discord interactions and lack of structured metadata, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter clearly documented in the schema itself. The description adds no additional parameter information beyond what's already in the schema, so it meets the baseline for high schema coverage but doesn't provide extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a reaction') and target resource ('to a message'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'discord_remove_reaction' or specify what types of reactions are supported beyond the basic concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'discord_remove_reaction' or 'discord_edit_message' (which might include reactions). There's no mention of prerequisites, permissions needed, or typical use cases in the Discord context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clean up a previously downloaded Discord attachment file
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to clean up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'clean up' implies deletion/removal, it doesn't specify whether this is reversible, what permissions are required, whether it affects the original Discord server content, or what happens if the file doesn't exist. For a tool that likely performs file system operations, this is insufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point. Every word serves a purpose - 'Clean up' (action), 'previously downloaded' (context), 'Discord attachment file' (resource). There's no wasted verbiage or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that performs file cleanup operations with no annotations and no output schema, the description is too minimal. It doesn't explain what 'clean up' means operationally (delete? move to trash?), what happens on success/failure, or any side effects. Given the potential for destructive file operations, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the single 'path' parameter well-documented in the schema. The description doesn't add any parameter-specific information beyond what's already in the schema (which states 'File path to clean up'). This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Clean up') and the target ('a previously downloaded Discord attachment file'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'discord_delete_message' or 'discord_remove_reaction' which also involve cleanup/deletion operations, though the specific resource type (attachment file) provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance - it mentions 'previously downloaded' which implies a prerequisite but doesn't specify when to use this tool versus alternatives. There's no explicit 'when-not' guidance or comparison to sibling tools like 'discord_delete_message' for message cleanup versus file cleanup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear your Discord presence/activity
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('clear') but doesn't explain what 'clear' entails (e.g., removes status, sets to offline, requires user permissions), potential side effects, or response behavior. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's mutation nature (clearing presence), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like what 'clear' means operationally, authentication needs, or expected outcomes, which are crucial for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter details, and it correctly implies no inputs are required, aligning with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Clear') and the resource ('your Discord presence/activity'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'discord_update_presence', but the verb 'clear' versus 'update' provides implicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage when clearing presence is needed, but it doesn't mention prerequisites, timing considerations, or how it relates to 'discord_update_presence' for setting a new presence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or get existing DM channel with a user
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | The user ID to create DM with |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'create or get existing', hinting at idempotent behavior, but fails to detail critical aspects like permissions required, rate limits, whether it returns a channel ID or object, or if it's a read-only or mutative operation. This leaves significant gaps for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without any fluff. It's front-loaded with the core action, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns (e.g., a channel object or ID), error handling, or how it interacts with sibling tools. Given the complexity of Discord operations and the lack of structured data, more context is needed for the agent to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'userId' clearly documented as 'The user ID to create DM with'. The description adds no additional parameter semantics beyond this, such as format examples or constraints. Given the high schema coverage, a baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('create or get') and resource ('DM channel with a user'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'discord_get_dm_channels' which might retrieve multiple DM channels, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'discord_get_dm_channels' for listing existing DMs or 'discord_send_message' for messaging without channel creation. There's no mention of prerequisites, error conditions, or typical use cases, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a message
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| messageId | Yes | The message ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Delete a message' implies a destructive mutation, but the description fails to mention critical behavioral aspects: whether this requires specific permissions (e.g., MANAGE_MESSAGES or ownership), if deletions are permanent/irreversible, rate limits, error conditions (e.g., message not found), or what happens upon success. This leaves significant gaps for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just three words, front-loading the core action ('Delete a message') with zero wasted language. Every word earns its place by directly stating the tool's function without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a destructive mutation with no annotations and no output schema), the description is incomplete. It lacks essential context: behavioral traits (permissions, permanence), usage guidelines, and any information about return values or errors. While the schema covers parameters well, the description fails to address the broader operational context needed for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for both 'channelId' and 'messageId' parameters. The description adds no additional semantic information beyond what's in the schema (e.g., format examples, relationship between parameters, or constraints). With high schema coverage, the baseline score of 3 is appropriate as the schema adequately handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('a message'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'discord_remove_reaction' or 'discord_cleanup_download' that also involve removal operations, nor does it specify what type of message (e.g., user's own message vs. any message with permissions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing appropriate permissions), when not to use it (e.g., for bulk deletion vs. single messages), or how it differs from related tools like 'discord_cleanup_download' or 'discord_remove_reaction' in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a Discord attachment and return it as MCP file reference
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Discord CDN URL of the attachment to download |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Download') and output ('return it as MCP file reference'), but lacks details on permissions required, rate limits, error handling, or whether the download is cached/persistent. This is a significant gap for a download operation with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and output without any wasted words. Every element ('Download a Discord attachment', 'return it as MCP file reference') directly contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a download operation with one parameter) and no output schema, the description is minimally adequate. It covers the basic purpose and output format but lacks behavioral context (e.g., side effects, error cases) and usage guidelines, which are needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'url' fully documented in the schema as 'Discord CDN URL of the attachment to download'. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Download a Discord attachment') and the resource ('Discord attachment'), distinguishing it from sibling tools like 'discord_list_attachments' (which lists) or 'discord_send_message' (which sends). It precisely defines the verb and target without redundancy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid Discord CDN URL from another tool like 'discord_list_attachments'), exclusions, or contextual usage scenarios, leaving the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a previously sent message
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| messageId | Yes | The message ID to edit | |
| content | Yes | New message content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like whether edits are rate-limited, if they require specific permissions (e.g., manage messages), what happens on failure, or Discord's edit constraints (e.g., time limits). The description is minimal and lacks crucial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse. Every word earns its place, achieving maximum clarity with minimal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects (permissions, rate limits, Discord constraints), error handling, or return values. Given the complexity of editing messages in Discord, more context is needed for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters clearly documented in the schema (channelId, messageId, content). The description adds no additional parameter semantics beyond implying 'content' is editable. Baseline score of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Edit') and resource ('a previously sent message'), making the purpose immediately understandable. It distinguishes from siblings like discord_send_message (create new) and discord_delete_message (remove). However, it doesn't specify what aspects can be edited beyond content, which the schema reveals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing message ownership/permissions), compare to discord_send_message for new messages, or indicate limitations like edit time windows in Discord. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about a Discord channel
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Get information' implies a read-only operation, it doesn't specify authentication requirements, rate limits, error conditions, or what specific information is returned. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a simple retrieval tool and gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description is minimally adequate. However, with no annotations and no output schema, it should ideally provide more context about what information is returned and any behavioral constraints. The description does the bare minimum for this tool's complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the single parameter 'channelId' is already documented in the schema. The description doesn't add any additional context about parameter usage, format requirements, or examples beyond what the schema provides, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'information about a Discord channel', making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'discord_get_dm_channels' or 'discord_get_message', which also retrieve Discord data but for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'discord_get_dm_channels' and 'discord_get_message' that also retrieve Discord information, there's no indication of when this specific channel information tool is appropriate versus those other retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get list of DM channels for the current user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but lacks critical details: it doesn't specify if this is a read-only operation, what permissions are required, how results are formatted (e.g., pagination, sorting), or potential rate limits. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without any wasted words. It directly communicates the action and target, making it easy to parse quickly. Every part of the sentence earns its place by specifying the resource type and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks context about authentication needs, return format, or error handling. Without annotations or output schema, the description should ideally provide more behavioral details to be fully complete for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the schema fully documents the absence of inputs. The description adds no parameter information, which is appropriate here since no parameters exist. A baseline of 4 is justified as the description doesn't need to compensate for any schema gaps, and it correctly implies no inputs are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get list of') and resource ('DM channels for the current user'), making the purpose immediately understandable. It distinguishes from siblings like discord_get_channel (general channels) and discord_get_friends (friends list), though it doesn't explicitly name these alternatives. The description is specific about the resource type and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing authentication), nor does it differentiate from similar tools like discord_get_channel or discord_create_dm. The agent must infer usage context from the tool name alone, which is insufficient for optimal selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get list of friends for the current user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a read-only operation but doesn't disclose authentication needs, rate limits, return format, or error conditions. This is inadequate for a tool that likely interacts with user data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently communicates the core functionality without any wasted words. It's front-loaded and appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is insufficiently complete. It doesn't explain what the returned friend list contains, how it's structured, or any behavioral constraints, leaving significant gaps for the agent to operate effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage, so the schema already fully documents the lack of inputs. The description appropriately doesn't add parameter details, maintaining focus on the tool's purpose without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get list of friends') and the resource ('for the current user'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'discord_get_dm_channels' or 'discord_get_channel' beyond the specific resource type, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage from the tool name alone among many Discord-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific message by ID with full attachment details
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| messageId | Yes | The message ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'full attachment details,' which adds context about return data, but lacks critical information such as authentication requirements, rate limits, error conditions (e.g., if the message doesn't exist), or whether this is a read-only operation (implied by 'Get' but not explicit).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Get a specific message by ID') and adds a useful detail ('with full attachment details'). There is no wasted verbiage, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the basic purpose and hints at return data, but without annotations or output schema, it should ideally mention behavioral aspects like read-only nature or error handling to be fully adequate for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (channelId and messageId) adequately. The description adds minimal value beyond the schema by implying the tool retrieves a message using these IDs, but it doesn't provide additional semantics like format examples or constraints beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('a specific message by ID'), distinguishing it from siblings like discord_get_message_history (which retrieves multiple messages) and discord_search_messages (which searches). However, it doesn't explicitly contrast with discord_get_channel, which might also retrieve messages indirectly, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like discord_get_message_history or discord_search_messages is provided. The description implies usage for retrieving a single known message ID, but it doesn't state prerequisites (e.g., needing channel access) or exclusions (e.g., not for bulk retrieval).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get message history from a Discord channel with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| limit | No | Number of messages to retrieve (1-100, default: 50) | |
| before | No | Get messages before this message ID | |
| after | No | Get messages after this message ID | |
| around | No | Get messages around this message ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a 'Get' operation but doesn't mention whether this requires specific permissions, rate limits, pagination behavior, or what the return format looks like. For a tool with 5 parameters and no output schema, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized for a retrieval tool and front-loads the essential information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns (message objects, format, structure), doesn't mention rate limits or permissions needed, and provides no guidance on usage context. For a message history tool in a Discord API context, this leaves too many open questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value by mentioning 'optional filtering' which hints at the before/after/around parameters, but doesn't provide additional context beyond what's in the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'message history from a Discord channel', making the purpose unambiguous. It distinguishes from some siblings like discord_get_message (single message) and discord_search_messages (search functionality), though not explicitly. However, it doesn't fully differentiate from all read operations like discord_get_channel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like discord_search_messages or discord_get_message. It mentions 'optional filtering' but doesn't explain what filtering options exist or when to choose this over other message retrieval tools. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all attachments in a Discord channel from recent messages
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| limit | No | Number of messages to scan for attachments (default: 50) | |
| imageOnly | No | Only show image attachments | |
| minSize | No | Minimum file size in KB | |
| maxSize | No | Maximum file size in KB |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions scanning 'recent messages' but doesn't specify how far back 'recent' extends, whether there are rate limits, authentication requirements, or what the output format looks like (e.g., list of URLs, file names, sizes). For a tool with 5 parameters and no output schema, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part of the sentence contributes directly to understanding what the tool does, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema, and no annotations), the description is insufficient. It doesn't explain the return values, potential errors, or behavioral nuances like how 'recent messages' are defined or if there are pagination considerations. For a tool that likely returns structured data about attachments, more context is needed to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each parameter's purpose and constraints. The description adds no additional parameter semantics beyond implying that attachments are sourced from 'recent messages,' which is already covered by the 'limit' parameter in the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all attachments') and resource ('in a Discord channel from recent messages'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'discord_search_messages' or 'discord_get_message_history' that might also retrieve message content including attachments, leaving room for ambiguity about when to choose this specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'discord_search_messages' or 'discord_get_message_history', nor does it mention any prerequisites or constraints beyond what's implied by the parameters. It lacks explicit usage context, making it unclear how this tool fits within the broader Discord toolset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a friend or cancel a friend request
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | User ID to remove as friend |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the action but does not specify whether this is a destructive operation, if it requires specific permissions, what happens to the friend relationship (e.g., irreversible removal), or any rate limits. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single, clear sentence that directly states the tool's purpose without any unnecessary words. It is front-loaded and efficient, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a social interaction tool with no annotations and no output schema, the description is insufficient. It lacks details on behavioral aspects (e.g., whether removal is permanent), usage context, or what to expect upon execution, making it incomplete for safe and effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the parameter 'userId' clearly documented as 'User ID to remove as friend'. The description does not add any additional meaning beyond this, such as format examples or constraints, so it meets the baseline for high schema coverage without compensating further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove' or 'cancel') and the resource ('a friend' or 'a friend request'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'discord_get_friends' (which lists friends) or 'discord_add_friend' (which adds friends), though the verb 'remove' inherently contrasts with 'add'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as whether it's for removing existing friends or canceling pending requests, or any prerequisites like user permissions. It lacks explicit context or exclusions, leaving usage ambiguous beyond the basic action stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a reaction from a message
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| messageId | Yes | The message ID to remove reaction from | |
| emoji | Yes | Emoji to remove (Unicode or custom emoji format) | |
| userId | No | User ID to remove reaction from (defaults to self) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Remove' implies a destructive/mutative operation, the description doesn't specify permission requirements, rate limits, whether removal is reversible, what happens if the reaction doesn't exist, or what the response looks like. For a mutation tool with zero annotation coverage, this is a significant gap in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded with the core action and target, making it immediately understandable. Every word earns its place, and there's no redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after removal (success/failure indicators), permission requirements, error conditions, or how this operation fits within Discord's reaction ecosystem. The description alone doesn't provide enough context for safe, effective use of this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds no additional parameter information beyond what's in the schema. The baseline score of 3 reflects adequate coverage when the schema does the heavy lifting, though the description doesn't compensate with any extra semantic context about parameter relationships or usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove') and target ('a reaction from a message'), making the purpose immediately understandable. It distinguishes from obvious siblings like 'discord_add_reaction' by specifying removal rather than addition. However, it doesn't differentiate from more distant siblings like 'discord_delete_message' or 'discord_edit_message' which also modify messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (like needing appropriate permissions), when removal is appropriate versus other message modifications, or how it differs from related tools like 'discord_delete_message' (which removes the entire message rather than just a reaction).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for messages in a Discord channel with text query and filters
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| query | Yes | Text to search for in messages | |
| limit | No | Number of results to return (1-25, default: 25) | |
| authorId | No | Filter by author user ID | |
| hasAttachments | No | Filter messages that have attachments | |
| hasImages | No | Filter messages that have images | |
| hasFiles | No | Filter messages that have files | |
| before | No | Search messages before this date (ISO format) | |
| after | No | Search messages after this date (ISO format) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'search' implies a read operation, the description doesn't mention important behavioral aspects: whether this requires specific permissions, rate limits, pagination behavior, or what the return format looks like. For a search tool with 9 parameters and no annotations, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without unnecessary words. It's appropriately sized for a search tool and front-loads the essential information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no output schema, no annotations), the description is insufficient. It doesn't explain what the search returns, how results are ordered, whether it's paginated, or any limitations. For a search operation in a messaging platform, users need to understand the result format and constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 9 parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'text query and filters', which aligns with the schema's documented parameters. With complete schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for messages in a Discord channel with text query and filters'. It specifies the verb ('search'), resource ('messages'), and domain ('Discord channel'), making it easy to understand. However, it doesn't explicitly differentiate from sibling tools like 'discord_get_message_history' or 'discord_get_message', which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'discord_get_message_history' and 'discord_get_message', there's no indication of when this search tool is preferred over those retrieval tools. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to a Discord channel, optionally with up to 10 files
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | Yes | The Discord channel ID | |
| content | No | Message content (max 2000 characters) | |
| files | No | Files to attach to the message | |
| tts | No | Send as text-to-speech message | |
| replyTo | No | Message ID to reply to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks critical behavioral details. It mentions file attachment limits but omits permissions needed, rate limits, message formatting options, error conditions, or what happens on success. For a write operation with no annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and includes the key optional feature. There's no wasted verbiage or redundancy, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like authentication needs, side effects, or response format, leaving significant gaps for an agent to understand tool invocation fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds minimal value by noting the optional file attachment capability (up to 10 files), which aligns with the schema's maxItems constraint but doesn't provide additional semantic context beyond what's already in structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Send a message') and target resource ('to a Discord channel'), with the optional capability of including files. It distinguishes itself from siblings like discord_edit_message or discord_delete_message by focusing on message creation, though it doesn't explicitly contrast with all messaging-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., channel access), compare with discord_edit_message for updates, or indicate when file attachments are appropriate versus other methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update your Discord presence/status
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Your status (online, dnd, idle, invisible, offline) | |
| activity | No | Activity to display | |
| afk | No | Whether you are AFK |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't disclose any behavioral traits like whether this requires authentication, if it's rate-limited, what happens when invalid parameters are provided, or what the expected response looks like. For a mutation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a tool with clear purpose and good schema documentation, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is minimally adequate. The purpose is clear and the schema provides complete parameter documentation, but there's no information about behavioral aspects, error conditions, or return values. Given the complexity of updating presence with multiple parameters and no structured safety information, the description should do more to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with all parameters well-documented in the schema itself. The description doesn't add any meaningful parameter semantics beyond what's already in the schema - it doesn't explain relationships between parameters, provide examples, or clarify edge cases. With complete schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('your Discord presence/status'), making the purpose immediately understandable. It distinguishes this from sibling tools like discord_clear_presence by specifying it's for updating rather than clearing. However, it doesn't explicitly mention what aspects of presence can be updated beyond the generic term.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when you might prefer discord_clear_presence instead, nor does it provide any context about prerequisites, permissions, or typical use cases. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0discord_clear_presence1 field changedInput schema / additionalPropertiesRemoved value: -falsediscord_get_dm_channels1 field changedInput schema / additionalPropertiesRemoved value: -falsediscord_get_friends1 field changedInput schema / additionalPropertiesRemoved value: -falsediscord_add_frienddiscord_add_reactiondiscord_cleanup_downloaddiscord_clear_presencediscord_create_dmdiscord_delete_messagediscord_download_attachmentdiscord_edit_messagediscord_get_channeldiscord_get_dm_channelsdiscord_get_friendsdiscord_get_messagediscord_get_message_historydiscord_list_attachmentsdiscord_remove_frienddiscord_remove_reactiondiscord_search_messagesdiscord_send_messagediscord_update_presenceScored across 19 tools
Each tool has a clearly distinct purpose with no overlap; for example, discord_get_message retrieves a single message, discord_get_message_history fetches historical messages, and discord_search_messages searches with queries, making misselection unlikely. The tools cover different actions (e.g., add/remove friend, send/edit/delete message) without ambiguity.
All tool names follow a consistent pattern: 'discord_' prefix followed by a verb_noun structure (e.g., discord_send_message, discord_get_channel). There are no deviations in style or convention, making the naming predictable and easy to parse.
With 19 tools, the count is slightly high but reasonable for a Discord server covering messaging, channels, friends, and presence. It includes core operations without being excessive, though it might feel heavy compared to simpler servers. The tools are well-scoped for the domain.
The tool set provides complete coverage for Discord interactions, including CRUD operations for messages (send, edit, delete, get), friends (add, remove, list), channels (get, DM management), and presence (update, clear). There are no obvious gaps, and agents can handle typical workflows without dead ends.
An MCP server that integrates with Discord to provide AI-powered features.
Official Duck Framework MCP server for AI-assisted development and project scaffolding.
Official MCP server for OmniDimension. Drive voice agents, dispatch calls, and run bulk campaigns.
Control your Discord community: send/read messages, manage channels and forums, and handle webhook…
