Notion MCP server has fundamental definition quality issues. While 13 tools are registered with proper naming (verb_noun convention) and basic parameter types, most lack adequate descriptions. Parameter descriptions are minimal (averaging 20-30 chars), which violates the 72-char baseline for production tools. Input schemas exist but are sparse, only IDs and file paths, with no constraints, enums, or validation guidance. Output schemas are completely undocumented. Error handling is generic (catch-all error messages). The server processes file paths as JSON data containers, which is a significant usability anti-pattern that complicates agent invocation. No indication of pagination, result limits, or structured output formatting. Overall, definitions would not pass code review by a principal tool engineer due to insufficient parameter guidance and missing output contracts.

• Expand every tool description from 1-5 words to 50-200 characters. Include WHAT the tool does, WHEN to use it (vs. similar tools), and any prerequisites. Example: 'Retrieve a page' → 'Fetch the full content and metadata of a Notion page by ID. Use this when you have the page_id from search results or a previous query. Returns page title, content blocks, and created/updated timestamps.'
• Add full parameter descriptions (min 50 chars) to every parameter. Include format guidance, valid ranges, and examples. E.g., 'The page_id (36-character UUID, e.g., 550e8400-e29b-41d4-a716-446655440000). Use search() first if you need to find a page by name.'
• Replace file_path-based parameters with direct data input. Instead of 'file_path to JSON', accept structured parameters (title, properties, content as nested objects). This aligns with the chat-data-model pattern and eliminates the friction of file serialization.
• Document output schemas for all tools. Create a schema reference for each tool's response, specifying field names, types, and whether pagination is supported. Example: 'Returns {page_id: string, title: string, properties: object, blocks: Block[], created_time: ISO8601, updated_time: ISO8601}'
• Add enums and constraints to parameters. E.g., for query_database, add a 'sort_by' parameter with enum [created_time, updated_time, title] and a 'limit' parameter with range [1, 100].
• Implement error categorization. Distinguish retryable errors (network failures, rate limits) from user-fixable errors (invalid IDs, missing permissions) from fatal errors. Return actionable guidance like 'Page not found. Try search() with the page title.'