list_document_comments
Retrieve and paginate comments on a specific document to review feedback, track collaboration, or find specific input from users. Supports optional anchor text inclusion.
Instructions
Retrieves comments on a specific document with pagination support.
IMPORTANT: By default, this returns up to 25 comments at a time. If
there are more than 25 comments on the document, you'll need to make
multiple calls with different offset values to get all comments. The
response will indicate if there
are more comments available.
Use this tool when you need to:
- Review feedback and discussions on a document
- See all comments from different users
- Find specific comments or questions
- Track collaboration and input on documents
Args:
document_id: The document ID to get comments from
include_anchor_text: Whether to include the document text that
comments refer to
limit: Maximum number of comments to return (default: 25)
offset: Number of comments to skip for pagination (default: 0)
Returns:
Formatted string containing comments with author, date, and
optional anchor text
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ||
| include_anchor_text | No | ||
| limit | No | ||
| offset | No |
Implementation Reference
- The main execution logic for the list_document_comments tool. Fetches comments via Outline API, handles pagination, and formats output using _format_comments.async def list_document_comments( document_id: str, include_anchor_text: bool = False, limit: int = 25, offset: int = 0, ) -> str: """ Retrieves comments on a specific document with pagination support. IMPORTANT: By default, this returns up to 25 comments at a time. If there are more than 25 comments on the document, you'll need to make multiple calls with different offset values to get all comments. The response will indicate if there are more comments available. Use this tool when you need to: - Review feedback and discussions on a document - See all comments from different users - Find specific comments or questions - Track collaboration and input on documents Args: document_id: The document ID to get comments from include_anchor_text: Whether to include the document text that comments refer to limit: Maximum number of comments to return (default: 25) offset: Number of comments to skip for pagination (default: 0) Returns: Formatted string containing comments with author, date, and optional anchor text """ try: client = await get_outline_client() data = { "documentId": document_id, "includeAnchorText": include_anchor_text, "limit": limit, "offset": offset, } response = await client.post("comments.list", data) comments = response.get("data", []) pagination = response.get("pagination", {}) total_count = pagination.get("total", len(comments)) return _format_comments(comments, total_count, limit, offset) except OutlineClientError as e: return f"Error listing comments: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}"
- Registers the list_document_comments tool with the MCP server using the @mcp.tool decorator inside register_tools.@mcp.tool( annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True) )
- Supporting function that formats the raw comments data into a human-readable markdown string with pagination and metadata.def _format_comments( comments: List[Dict[str, Any]], total_count: int = 0, limit: int = 25, offset: int = 0, ) -> str: """Format document comments into readable text.""" if not comments: return "No comments found for this document." output = "# Document Comments\n\n" # Add pagination info if provided if total_count: shown_range = ( f"{offset + 1}-{min(offset + len(comments), total_count)}" ) output += f"Showing comments {shown_range} of {total_count} total\n\n" # Add warning if there might be more comments than shown if len(comments) == limit: output += "Note: Only showing the first batch of comments. " output += f"Use offset={offset + limit} to see more comments.\n\n" for i, comment in enumerate(comments, offset + 1): user = comment.get("createdBy", {}).get("name", "Unknown User") created_at = comment.get("createdAt", "") comment_id = comment.get("id", "") anchor_text = comment.get("anchorText", "") # Extract data object containing the comment content data = comment.get("data", {}) # Convert data to JSON string for display try: import json text = json.dumps(data, indent=2) except Exception: text = str(data) output += f"## {i}. Comment by {user}\n" output += f"ID: {comment_id}\n" if created_at: output += f"Date: {created_at}\n" if anchor_text: output += f'\nReferencing text: "{anchor_text}"\n' if data: output += f"\nComment content:\n```json\n{text}\n```\n\n" else: output += "\n(No comment content found)\n\n" return output
- src/mcp_outline/features/documents/__init__.py:32-32 (registration)Higher-level registration that invokes register_tools from document_collaboration module, making list_document_comments available.document_collaboration.register_tools(mcp)
- Function signature with type hints and defaults defining the input schema (parameters) and output type (str). Docstring provides detailed description.async def list_document_comments( document_id: str, include_anchor_text: bool = False, limit: int = 25, offset: int = 0, ) -> str: