Notion MCP server has 14 tools with complete input schemas and basic descriptions. Naming follows verb_noun convention (notion_page_get, notion_database_query, etc.). However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool vs. alternatives. Parameter descriptions exist but are minimal (avg ~40 chars vs. baseline 72). No output schemas documented. Error handling is absent, tools return raw API responses without recovery guidance. Missing tool annotations (readOnlyHint, destructiveHint) despite clear risk classifications. No pagination guidance in list-returning tools.

• Add output schemas to all tools. Document the structure of notion_page_get response (e.g., {id, title, content, created_time, last_edited_time}), notion_database_query results (e.g., {results: [{id, properties}], has_more, next_cursor}), and notion_search response.
• Expand tool descriptions to 150-250 chars. Include WHEN to use (e.g., 'Use this to retrieve a single page by ID. For searching by title, use notion_search_by_title instead.'), what it returns, and any prerequisites (e.g., 'Requires page ID; use notion_search to find pages first').
• Add tool annotations: mark notion_page_delete, notion_block_delete, notion_page_update, notion_database_update_page with destructiveHint=true; mark all read-only tools with readOnlyHint=true; mark idempotent tools (e.g., notion_page_get) with idempotentHint=true.
• Document filter and properties parameter formats. For notion_database_query, provide an example filter structure or link to Notion API docs. For notion_database_create_page and notion_database_update_page, document the properties object schema (e.g., {Name: {title: [{text: {content: string}}]}, Status: {select: {name: string}}}).
• Add error handling with recovery guidance. Wrap API calls in try-catch; return structured errors like {error: 'invalid_filter', message: 'Filter syntax error', suggestion: 'Use notion_database_get_schema to see available properties', retryable: false}.