Loading ToolBench
A Model Context Protocol server that provides tools for interacting with the Notion API, enabling operations on pages, databases, blocks, users, and comments
This Notion MCP server has 22 tools with consistent naming (all verb_noun structure: notion_<action>_<resource>), but definition quality is uneven. Descriptions range from minimal (notion_retrieve_block: 27 chars) to adequate (notion_append_block_children: 165 chars), averaging ~90 chars, below the production baseline of 194 chars. Most critically, parameter schemas are severely underspecified: complex nested types like 'children' (array of blocks), 'properties' (object), 'title' (array of rich text), and 'parent' (object) have empty or opaque item schemas. The source shows 'items: blockObjectSchema' and 'items: richTextObjectSchema' but these are references to undefined schemas in the codebase, no inline schema definitions are visible. This violates the JSON Schema clarity requirement: callers cannot understand what structure to provide. Error handling is absent, no recovery guidance, no actionable error messages shown. Output schemas are completely undocumented. Pagination support exists (start_cursor, page_size in ~6 tools) but return value structure and total_count are never documented. The server correctly avoids exposing secrets as parameters (uses environment token via package.json 'your_notion_token_here' pattern). Tool composition is sound, each tool has one clear responsibility. However, several tools combine concepts: notion_create_workflow (trigger + actions array) and notion_create_recurring_task (task_properties + recurrence_pattern) require deep nested structures without inline schema clarity.
Append new children blocks to a specified parent block in Notion. Requires insert content capabilities. You can optionally specify the 'after' parameter to append after a certain block.
Create a comment in Notion. This requires the integration to have 'insert comment' capabilities. You can either specify a page parent or a discussion_id, but not both.
Create a database in Notion
Create a new item (page) in a Notion database
Create a recurring task in a Notion database
Create a workflow in Notion
Complex nested schemas (blockObjectSchema, richTextObjectSchema) are referenced but not inlined. Callers cannot see what structure is required for 'children', 'items', or 'title' parameters. This violates JSON Schema clarity, LLMs cannot infer valid nested structure.
Object-type parameters ('properties', 'parent', 'trigger', 'actions', 'column_mappings') have no schema definition. Description only says 'Properties to update' or 'Parent object', LLMs cannot determine valid field names, types, or whether nesting is allowed.
Output schemas are completely undocumented. Tools return lists (notion_retrieve_block_children, notion_list_all_users, notion_search, notion_query_database) but no documentation of result structure, field names, or whether results are paginated.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 45 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 28 | - | v1 |
Delete a block in Notion
Export data from a Notion database to a CSV file
Import data from a CSV file into a Notion database
List all users in the Notion workspace. **Note:** This function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors.
Query a database in Notion
Retrieve a block from Notion
Retrieve the children of a block
Retrieve the bot user associated with the current token in Notion
Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.
Retrieve a database in Notion
Retrieve a page from Notion
Retrieve a specific user by user_id in Notion. **Note:** This function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors.
Search for pages and databases in Notion
Update an existing block in Notion
Update a database in Notion
Update properties of a page or an item in a Notion database
Many descriptions are under 50 characters (notion_retrieve_block: 27 chars, notion_retrieve_page: 25 chars). These are too terse to guide LLM tool selection, LLMs need WHAT, WHEN, and WHY context.
No error handling guidance. Tools offer no recovery hints (e.g., 'User not found, try search_users() first') or actionable error messages. LLMs cannot self-recover on failures.
Parameter descriptions lack constraints and examples. 'page_size' (max 100) and 'interval' (numeric) have no min/max declarations. 'frequency' enum is not shown in description, only visible in schema. LLMs cannot infer valid ranges.
notion_create_comment and notion_create_workflow have conditional parameter dependencies (parent XOR discussion_id; trigger + actions are co-required) documented only in description text, not enforced in schema (no oneOf, allOf, or required array patterns).