Notion MCP has well-structured tool definitions with consistent naming (verb_noun pattern) and complete input schemas. However, descriptions are generic and lack LLM-optimization guidance. Parameter descriptions are minimal (often single phrases like 'The ID of the database to retrieve'). Output schemas are not documented, LLMs cannot predict response structure. Error handling is absent from tool definitions. No tool annotations (readOnlyHint/destructiveHint) despite clear risk stratification. The server implements 10 tools covering core Notion operations, but lacks the depth of guidance needed for reliable agent planning.

• Add output schemas to every tool. Document the response structure (e.g., notion_search returns {results: [{id, title, type, url}], has_more: bool}). This enables agents to plan chained calls.
• Expand tool descriptions to 100-200 chars with WHEN/WHAT/RETURN structure. E.g., 'Retrieve a database by ID. Use this to fetch schema and properties before querying. Returns database metadata including property definitions and icon.'
• Add readOnlyHint and destructiveHint annotations to tool definitions. Mark create_*, update_*, append_* with destructiveHint=true so agents know these have side effects.
• Document parameter formats and constraints in descriptions. E.g., 'filter: Notion filter object (e.g., {property: "Status", select: {equals: "Done"}}). See Notion API docs for full syntax.'
• Add error handling guidance: 'If database_id is invalid, returns 404. Try notion_search to find the correct database. If rate-limited (429), retry after 1 second.'

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

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