nc-mcp-server

pin_message

Idempotent

Pin a message to the top of a conversation for all participants, with optional expiry or until unpinned. Requires moderator rights to highlight important announcements.

Instructions

Pin a message to the top of the conversation for everyone. Needs moderator rights.

Pinned messages are listed by list_shared_items with item_type "pinned".

Args: token: The conversation token. message_id: The message to pin. until: When the pin should expire, as an ISO 8601 time with time zone (default: until someone unpins it). Talk removes expired pins on its next background job run.

Returns: JSON with the pinned message, or a note that it was already pinned.

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": {
      "token": "<token>",
      "message_id": "<message_id>"
    },
    "name": "pin_message"
  }
}

Input Schema

Name	Required	Description	Default
`token`	Yes
`until`	No
`message_id`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.9.0Oct 1, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Adds real context beyond the annotations: moderator-permission requirement, the default lifetime (until unpinned), that expired pins are cleared on the next background job run, and that an already-pinned message returns a note rather than an error. This aligns with idempotentHint=true. Missing rate-limit or failure-mode detail keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Front-loads purpose and precondition, then uses clean Args/Returns sections. Every sentence adds information; nothing is redundant with the schema or annotations.

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 3-param mutation with a sparse schema, the description covers purpose, authorization, parameter formats, expiration behavior, and return shape. An output schema exists, so the return note is a bonus rather than a necessity.

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

Parameters5/5

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

Schema coverage is 0%, so the description carries the full burden and does so: it documents all three params, explains `until` as ISO 8601 with time zone, states its default semantics, and clarifies that `message_id` is the message to pin.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (pin) and resource (message) with scope ('to the top of the conversation for everyone'), which cleanly separates it from sibling unpin_message and from list_shared_items. An agent can identify the action without opening the schema.

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

Usage Guidelines4/5

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

Gives a clear precondition ('Needs moderator rights') and points to where the result surfaces (list_shared_items with item_type "pinned"). It does not explicitly name unpin_message as the inverse operation or state when not to pin, so it falls short of a full 5.

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

Deploy Server