MCP server for Notion integration that allows AI assistants to create, read, update, and search Notion pages and databases
Notion MCP server has 5 tools with basic naming (verb_noun structure) and descriptions present for each tool. However, significant gaps exist: parameter descriptions are inconsistent in depth; output schemas are not formally documented; error handling is rudimentary (returns error objects but no recovery guidance); and several tools have incomplete or unclear parameter documentation. The code shows functional implementations but lacks the rigor expected of production-grade agent tools. Per-tool analysis reveals naming is acceptable but descriptions are generic (100-150 chars, below the 50-200 char LLM-optimized sweet spot), and schemas, while present in code, are not formally documented in output structure. Average per-tool score: 51.
Append new content to an existing Notion page.
Create a new page in Notion.
Retrieve the content of a specific Notion page.
Search for pages in Notion by title or content.
Update a Notion page's properties.
Output schemas are not formally documented. Tools return dictionaries with 'success', 'error', 'page_id', 'url', 'results', etc., but these structures are never declared to the LLM. Agents must infer output structure from examples, causing confusion when calling downstream tools.
Descriptions lack specificity and LLM-optimization. Most descriptions are 70-130 chars and generic (e.g., 'Create a new page in Notion'). LLM-optimized descriptions (50-200 chars) should include WHAT, WHEN, and WHY. For example: 'create_page' should note that it creates a writable resource with optional parent hierarchy, and clarify when to use vs append_to_page.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 51 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 46 | - | v1 |
No documented return schemas. The code returns success/error dicts with varying fields. Example: create_page returns {success, page_id, url, message} on success and {success, error} on failure. LLMs cannot plan downstream calls without knowing output structure, e.g., does search_pages return 'id' or 'page_id'? Mismatch forces extra lookup calls.
Error handling does not guide recovery. Errors are returned as {success: false, error: 'message'} with no categorization (retryable vs user-fixable vs fatal). Example: 'No parent page specified and no existing pages found' tells the user to provide parent_page_id, but doesn't suggest search_pages to discover a valid page ID.
Non-idempotent operation (append_to_page) is not flagged. append_to_page appends content on every call, repeated calls with the same parameters create duplicates. Agents retry on ambiguous failures, risking duplicate appends. No idempotentHint in tool annotation, no deduplication key, no warning in description.
Destructive operations (update_page with archived=true, create_page which is permanent) lack confirmation or dry-run. No support for MRTR (Multi-Round-Trip Request) with result='input_required' to confirm before executing.
Tool naming conflicts risk LLM confusion. 'get_page_content' retrieves content blocks (structured), but 'update_page' modifies properties (title, archive status), not content. And 'append_to_page' appends content. The distinction is not obvious from names alone, LLMs may incorrectly choose update_page when they mean append_to_page.
Parameter descriptions lack actionable constraints. Example: 'parent_page_id' in create_page is described as 'Optional ID of the parent page. If not provided, creates a top-level page.' But the code shows it searches for a fallback page, which contradicts the description. Format, examples, and fallback behavior are undocumented.
Search result limits are not documented. search_pages accepts page_size with a default of 10, but no maximum is enforced or mentioned. If an agent requests page_size=1000, will it work? Will it timeout? This invites hallucinated large requests.
create_page behavior with no parent is unclear and potentially broken. Code attempts to search for an existing page as fallback, but this is fragile and undocumented. If no pages exist, the tool fails with a user-facing error ('No parent page specified and no existing pages found') that doesn't guide recovery. Should require parent_page_id or provide a configuration option.