mcp-server-mattermost

update_bookmark_sort_order

Idempotent

Reorders a channel bookmark to a specified position, automatically adjusting other bookmarks and returning updated positions.

Instructions

Reorder a channel bookmark.

Moves the bookmark to the specified position. Other bookmarks are automatically adjusted. Returns all affected bookmarks with updated positions.

Note: Requires Entry, Professional, Enterprise, or Enterprise Advanced edition (not available in Team Edition). Minimum version: v10.1.

Input Schema

TableJSON Schema

Name	Required	Description
`channel_id`	Yes	26-character channel identifier (e.g., 'o5w8h47pdfbzjc4d8w7dhnhren')
`bookmark_id`	Yes	26-character bookmark identifier (e.g., 'o5w8h47pdfbzjc4d8w7dhnhren')
`new_sort_order`	Yes	New position in bookmark list

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.6.1Sep 10, 2026

addedOutput schema / properties / result / items / properties / file

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "description": "Uploaded file metadata.\n\nNote: Go source uses CreatorId field name, but JSON response uses \"user_id\".\n\nSee: https://github.com/mattermost/mattermost/blob/master/server/public/model/file_info.go",
+      "properties": {
+        "channel_id": {
+          "description": "Channel where file was uploaded",
+          "type": "string"
+        },
+        "create_at": {
+          "description": "Upload timestamp in milliseconds",
+          "type": "integer"
+        },
+        "delete_at": {
+          "description": "Deletion timestamp",
+          "type": "integer"
+        },
+        "extension": {
+          "description": "File extension without dot",
+          "type": "string"
+        },
+        "has_preview_image": {
+          "default": false,
+          "description": "Has generated preview",
+          "type": "boolean"
+        },
+        "height": {
+          "default": 0,
+          "description": "Image height in pixels",
+          "type": "integer"
+        },
+        "id": {
+          "description": "Unique file identifier",
+          "type": "string"
+        },
+        "mime_type": {
+          "description": "MIME type",
+          "type": "string"
+        },
+        "name": {
+          "description": "File name",
+          "type": "string"
+        },
+        "post_id": {
+          "default": "",
+          "description": "Associated post ID",
+          "type": "string"
+        },
+        "size": {
+          "description": "File size in bytes",
+          "type": "integer"
+        },
+        "update_at": {
+          "description": "Last update timestamp",
+          "type": "integer"
+        },
+        "user_id": {
+          "description": "Uploader user identifier (CreatorId in Go)",
+          "type": "string"
+        },
+        "width": {
+          "default": 0,
+          "description": "Image width in pixels",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "id",
+        "user_id",
+        "channel_id",
+        "create_at",
+        "update_at",
+        "delete_at",
+        "name",
+        "extension",
+        "size",
+        "mime_type"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "File metadata for file bookmarks"
+}

removedOutput schema / properties / result / items / properties / file_info

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "File metadata for file bookmarks"
-}

First observedv0.5.1Jul 29, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare idempotentHint and non-destructive, while the description goes further by explaining that other bookmarks get automatically adjusted and that the response returns all affected bookmarks with updated positions. It also adds clearly an edition/version constraint (not in Team Edition, min v10.1). No contradiction with the annotations.

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?

The description is extremely concise and front-loaded: the verb phrase appears in the first sentence. It says everything necessary in a compact two-sentence form plus a short note about edition/version. There is no redundancy or unnecessary elaboration.

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?

Although an output schema exists and the description need not explain return values, the description sensibly mentions that the operation returns all affected bookmarks with updated positions, which is enough for the agent. It also discloses the edition/version constraints, which is critical for actionable use. Could add a little about out-of-range positions or failure behavior, but for a simple reorder tool it's essentially 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?

The schema has 100% description coverage; the parameters channel_id, bookmark_id, and new_sort_order are fully explained there. The description only restates the meaning of new_sort_order in prose ('moves the bookmark to that specified position') without adding extra detail such as examples or ranges beyond the schema. Baseline 3 is appropriate.

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 'Reorder a channel bookmark' – a specific verb and resource – then clarifies the behavior: 'Moves the bookmark to the specified position.' This clearly distinguishes it from the sibling update_bookmark, which implies changing bookmark content, and from create/delete/list_bookmarks. The purpose is unambiguous.

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?

Gilt clearly states what the tool does (reorders by moving a bookmark to a position and adjusting others), but it does not explicitly say when to choose this tool versus alternatives like update_bookmark, nor does it describe any when-not-to-use context. The usage scenario is reasonable but implied rather than stated.

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