Skip to main content
Glama

mcp-notion__notion-get-comments

Read-onlyIdempotent

Get comments and discussions from a Notion page.

Returns page-level and inline discussions in XML format. Long results are shortened:

  • If shown-count is less than total-count, some discussions were left out. Up to 50 are listed as <omitted-discussion id="discussion://..."/>: pass that URL as discussion_id to fetch it. If omitted-truncated="true", more were left out; fetch with include_discussions: true may show their URLs.

  • Each discussion has comment-count (comments shown) and total-comment-count. A discussion that does not fit keeps its newest comments. When older comments were left out, it has next-cursor: pass it as cursor with that discussion_id to get the next older comments. Repeat until a response has no next-cursor. If it has reactions-truncated="true", some of its reactions were left out to fit. On supported Business connections, pending suggested edits use kind="suggested_edit" and their discussion:// URL can be passed to get_suggested_edit. Resolved suggestion… Through Royally: its server marks it read-only, so it runs straight away.

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": {
      "page_id": "<page_id>"
    },
    "name": "mcp-notion__notion-get-comments"
  }
}

Input Schema

NameRequiredDescriptionDefault
skillNoFor tracking only: the name of the agent skill you are following for this task, such as notion-meeting-prep. Omit if you are not following a skill.
cursorNoThe `next-cursor` value from a discussion in an earlier response. Returns that discussion's older comments. Requires `discussion_id`.
page_idYesThe page ID, with or without dashes, or a Notion page URL.
site_idNoSite to run this tool on: ded71e55-0da4-4a52-8f14-1224fa9979b9 (https://mcp.notion.com/mcp)
discussion_idNoFetch a specific discussion by ID or discussion URL (e.g., discussion://pageId/blockId/discussionId).
include_resolvedNoInclude resolved discussions in the response. Defaults to false.
instructions_versionNoNotion setup instructions version, such as 0.0.2. Omit if unknown.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, yet the description still adds real depth: XML output shape, shown-count vs total-count truncation, omitted-discussion markers, reactions-truncated, and the fact that a discussion keeps its newest comments when trimmed. Deductions apply because the final sentences are truncated to the point of being unreadable, and nothing is said about how include_resolved affects the result.

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

Conciseness3/5

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

The purpose and output format are correctly front-loaded, but the body is a dense block of nested pagination edge cases, and the ending degrades into an unreadable fragment ("Resolved suggestion… Through Royally: its server marks it read-only, so it runs straight away") that wastes space and confuses the reader.

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?

With no output schema, the description carries the burden of explaining returns and does so well — XML format, truncation flags, cursors, and suggested-edit kind. Against 7 parameters and rich annotations, the remaining gaps are the truncated final passage and the absent explanation of include_resolved's effect on what the caller sees.

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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the operational link between outputs and parameters — the omitted-discussion URL is fed in as discussion_id, and next-cursor is fed in as cursor with that discussion_id. It does not explain include_resolved, site_id, skill, or instructions_version, but those are already documented in the schema.

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

Purpose4/5

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

The first sentence states a specific verb and resource ("Get comments and discussions") scoped to a Notion page, and the second sentence names the return format (XML, page-level and inline discussions). It also distinguishes the suggested-edit subset by pointing to get_suggested_edit, but it does not contrast itself with other read tools like notion-fetch or notion-search.

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?

There is substantial procedural guidance for follow-up invocations (pass the omitted-discussion URL as discussion_id; pass next-cursor as cursor and repeat until no next-cursor remains), which is genuine when-to-call guidance. However, there is no statement of when to choose this tool over sibling read tools, and the trailing text about read-only resolution is garbled and provides no usable guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources