discord-mcp

discord_pin_message

Idempotent

Pin or unpin a Discord message in a channel or thread via a boolean flag, enabling controlled management of pinned content with required permissions and pin limits.

Instructions

Pin or unpin a message in a channel, controlled by the pin flag. Requires the Pin Messages permission (a dedicated permission since early 2026, separate from Manage Messages). A channel holds at most 250 pins. Idempotent: pinning an already-pinned message (or unpinning an unpinned one) has no additional effect.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "channel_id": "<channel_id>",
      "message_id": "<message_id>",
      "pin": "<pin>"
    },
    "name": "discord_pin_message"
  }
}

Input Schema

Name	Required	Description
`pin`	Yes	true to pin the message, false to unpin it.
`channel_id`	Yes	ID (snowflake) of the channel or thread containing the message.
`message_id`	Yes	ID of the message to pin or unpin.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.2.0Sep 6, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
Changed2 schema fields changedv2.0.0Jun 27, 2026
- addedInput schema / properties / channel_id / pattern
```
Added value: +"^\\d{17,20}$"
```
- addedInput schema / properties / message_id / pattern
```
Added value: +"^\\d{17,20}$"
```

Changed3 schema fields changedv1.6.0May 28, 2026

addedInput schema / properties / channel_id / description

Added value: +"ID (snowflake) of the channel or thread containing the message."

addedInput schema / properties / message_id / description
```
Added value: +"ID of the message to pin or unpin."
```

changedInput schema / properties / pin / description

Previous value: -"true to pin, false to unpin."New value: +"true to pin the message, false to unpin it."

Addedv1.5.0May 8, 2026
Removedv1.0.0May 1, 2026
First observedv0.1.0Mar 21, 2026

TDQS

A3.9/5.0

Behavior4/5

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

The annotations already declare idempotentHint=true and destructiveHint=false, so the description's idempotency sentence repeats structured data rather than adding to it. It does, however, contribute real behavioral context beyond the annotations: the dedicated Pin Messages permission (separate from Manage Messages) and the hard 250-pin channel cap that can cause failure. It says nothing about error behavior when the cap is hit or about rate limits, keeping it 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.

Conciseness4/5

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

Four short sentences with the action front-loaded and constraints following in descending order of importance. Slight redundancy in the idempotency sentence, which duplicates the idempotentHint annotation, but nothing is bloated or buried.

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?

For a simple three-parameter mutation with full schema coverage and annotations, the description covers the essentials: permission requirement, capacity limit, and repeat-call behavior. Only the absence of any note on failure modes (e.g. what happens at the 250-pin cap) keeps it from being fully complete.

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%, so all three parameters (including the boolean 'pin' semantics) are fully documented in the input schema. The description's 'controlled by the pin flag' merely restates that, adding no format, constraint, or edge-case guidance 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?

The description opens with a specific verb pair and resource ('Pin or unpin a message in a channel') and immediately names the controlling parameter ('controlled by the pin flag'). That is enough to distinguish it from the read-only sibling discord_fetch_pinned_messages and from discord_delete_message without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied through prerequisites: it states the Pin Messages permission is required, which tells the agent under what conditions the call can succeed. However, it never names an alternative tool or a when-not condition (e.g. 'to read pins use discord_fetch_pinned_messages' or 'use delete_message to remove rather than unpin').

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

Deploy Server