Notion MCP has critical definition gaps. All 5 tools lack parameter descriptions, the rubric requires every parameter to have a description explaining what it controls. Tool descriptions exist but are minimal (10-30 chars), below the 50-200 char baseline for LLM-optimized descriptions. No output schemas are documented. Input schemas are present with types but lack the descriptive context LLMs need. Error handling is absent, tools return generic dicts without recovery guidance. The server exposes a hardcoded API token in source code (ARTICLE_COLLATION_TOKEN), violating secret-injection patterns. No tool annotations (readOnlyHint, destructiveHint) despite having both read and write operations.

• Add parameter descriptions to all tools. For each parameter, explain what it controls, expected format, and constraints. Example: 'page_id (string): The Notion page ID to query. Format: 32-character UUID without hyphens (e.g., a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6).'
• Move ARTICLE_COLLATION_TOKEN to an environment variable (NOTION_API_TOKEN) and load it via os.getenv(). Never hardcode secrets in source code.
• Document output schemas for each tool. Specify field names, types, and meanings. Example for list_database_pages: 'Returns list[str]: Array of page IDs (32-char UUIDs). Empty list if database has no pages.'
• Expand tool descriptions to 50-200 characters. Include WHAT (action), WHEN (use case), and PREREQUISITES. Example: 'Update the Name property of a Notion page. Use this after retrieving a page_id via list_database_pages. Returns success status and the updated title.'
• Add error handling with recovery guidance. Return structured errors with actionable messages. Example: '{"status": "error", "code": "page_not_found", "message": "Page ID not found. Verify the page_id is correct and you have access.", "recovery": "Try list_database_pages() to find valid page IDs."}'
• Add tool annotations (readOnlyHint, destructiveHint) to distinguish read vs write operations. Mark query_all_databases and list_database_pages with readOnlyHint=true; mark update_page_title, fill_url_from_existing, batch_process_fill_url with destructiveHint=true.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry