discord-mcp

discord_list_pins

Read-onlyIdempotent

List pinned messages from a Discord channel or thread, newest first with pin times, so you can review and paginate saved pins.

Instructions

List the pinned messages of a channel or thread, newest pin first, each with its pin time. To pin a message use discord_create_pin, and to unpin use discord_delete_pin. Page with before=next_before while has_more is true. Bot permissions it may need: View Channel, Read Message History. Read-only; safe to retry.

Input Schema

Name	Required	Description
`limit`	No	Max number of pinned messages to return (1-50; default is 50)
`before`	No	ISO 8601 date and time with seconds, for example 2026-11-05T18:00:00Z; cursor to fetch pins created before this time (use next_before)
`channel_id`	Yes	ID of the channel or thread to list pinned messages from

Output Schema

Name	Required	Description	Default
`items`	Yes
`has_more`	Yes
`next_before`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv0.1.2Nov 4, 2026
- addedInput schema / properties / before / description
```
Added value: +"ISO 8601 date and time with seconds, for example 2026-11-05T18:00:00Z; cursor to fetch pins created before this time (use next_before)"
```
- changedInput schema / properties / before / pattern
```
Previous value: -"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"New value: +"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
```
- addedInput schema / properties / channel_id / description
```
Added value: +"ID of the channel or thread to list pinned messages from"
```
- addedInput schema / properties / limit / description
```
Added value: +"Max number of pinned messages to return (1-50; default is 50)"
```
- addedOutput schema / properties / items / items / properties / message / properties / attachments / items / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- removedOutput schema / properties / items / items / properties / message / properties / author / properties / global_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / items / items / properties / message / properties / author / properties / global_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- addedOutput schema / properties / items / items / properties / message / properties / author / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedOutput schema / properties / items / items / properties / message / properties / channel_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- removedOutput schema / properties / items / items / properties / message / properties / edited_timestamp / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / items / items / properties / message / properties / edited_timestamp / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- addedOutput schema / properties / items / items / properties / message / properties / id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedOutput schema / properties / items / items / properties / message / properties / message_reference / properties / channel_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedOutput schema / properties / items / items / properties / message / properties / message_reference / properties / guild_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- addedOutput schema / properties / items / items / properties / message / properties / message_reference / properties / message_id / description
```
Added value: +"Discord snowflake ID as a numeric string"
```
- removedOutput schema / properties / next_before / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / next_before / type
```
Added value: +[
+  "string",
+  "null"
+]
```
First observedv0.1.0Nov 3, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description nonetheless adds genuinely new behavior: result ordering, that pin timestamps are returned, the pagination cursor loop, and the specific bot permissions (View Channel, Read Message History) required. "Read-only; safe to retry" merely restates annotations, but the permission and pagination details carry real weight.

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?

Four short sentences, front-loaded with purpose then routing, then pagination, then permissions. No filler, and the most decision-relevant information (what it lists and which siblings do the mutations) comes first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter read tool with an output schema, this covers everything an agent needs: what is returned, ordering, how to paginate, which sibling performs mutations, and what permissions may be missing. Return-value details are correctly delegated to the output schema rather than restated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description goes beyond it by explaining that the `before` cursor should be fed from `next_before` and sustained while `has_more` is true — meaning the schema alone does not convey. `limit` and `channel_id` semantics are left to the schema, which documents them adequately.

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?

"List the pinned messages of a channel or thread" gives a specific verb plus resource, and the description further pins down ordering ("newest pin first") and per-item content ("each with its pin time"). It distinguishes itself from the mutation siblings discord_create_pin and discord_delete_pin by name, so an agent can separate the three without opening any schema.

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

Usage Guidelines5/5

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

It routes the agent explicitly: use discord_create_pin to pin, discord_delete_pin to unpin, this tool to read. It also supplies the pagination protocol ("Page with before=next_before while has_more is true") and the bot permission prerequisites, which is exactly the when/how context an agent needs before calling.

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