16 tools with complete JSON Schema input definitions and descriptions present for all tools. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool or dependencies between them. Parameter descriptions are minimal (avg ~40 chars vs baseline 72). No output schemas documented. Error handling absent. Tool names follow verb_noun convention well (retrieve_, create_, update_, delete_, append_, query_). Missing: actionable error messages, recovery guidance, parameter constraints (enums for sort direction exist but most params lack validation hints), and composition guidance for multi-step workflows.

• Document output schemas for all tools. Example: retrieve_page should return {page_id, title, properties, created_time, last_edited_time}. This enables LLMs to chain tools (e.g., retrieve_page → update_page_properties).
• Expand tool descriptions to 100-200 chars with WHEN guidance. Example: 'Retrieve a single page by ID. Use this after search() returns a page_id, or when you have a page URL. Returns page properties, content structure, and metadata.'
• Add parameter constraints and examples in descriptions. Example: 'children: Array of block objects. Each block must have a 'type' field (paragraph, heading_1, etc.) and a 'content' field with rich text. See Notion API docs for valid block types.'
• Implement error handling with recovery hints. Example: If block_id is invalid, return 'Block not found. Try search() to find the correct block ID, or retrieve_block_children() to list available blocks in the parent.'
• Add tool annotations (destructiveHint, readOnlyHint) to help agents understand side effects. Mark delete_block, update_page_properties, create_database_item as destructive; mark retrieve_* as readOnly.