Loading ToolBench
MCP server for Notion API — manage pages, blocks, databases, data sources, comments, and users
Notion MCP demonstrates strong schema coverage and comprehensive tool naming conventions. All 25 tools are explicitly defined with consistent verb_noun naming (notion_search, notion_create_page, notion_get_page, etc.). Input schemas are present and mostly well-structured with JSON Schema types. Tool annotations are correctly implemented (readOnlyHint, destructiveHint, idempotentHint). However, several critical gaps reduce the score: (1) output schemas are NOT documented, the rubric requires 'Document the output schema' to guide LLM planning, but no return types are specified for any tool; (2) parameter descriptions are present but many lack concrete constraints (range, format, regex patterns), e.g., 'page_size' is described as 'Results per page (max 100)' but this constraint is not in the schema itself; (3) error handling is absent, no recovery guidance, categorization of errors, or actionable error messages; (4) some descriptions are vague (e.g., 'Retrieve a database by ID' for notion_get_database lacks WHEN to use it vs. notion_query_database); (5) parameter relationships are undocumented (e.g., parent object structure in notion_create_page varies by context but this dependency is not explicitly stated). Strengths: consistent naming, all tools have descriptions, comprehensive parameter coverage, proper use of enums (filter_object, sort_direction), and tool annotations show intent.
Append content blocks to a page or block. Max 100 blocks, 2 levels of nesting. Common types: paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, to_do, code, quote, callout, divider, table.
Create a comment on a page or discussion thread.
Create a new data source (table) under an existing database. Data sources are individual tables within a database (API 2025-09-03).
Create a new database in Notion.
Create a new page in Notion. Set parent as a data source (data_source_id) or another page (page_id). Provide properties matching the parent schema. Optionally include initial content blocks.
Delete (archive) a block. The block is moved to trash.
Output schemas are completely missing across all 25 tools. The rubric requires 'Document the output schema. LLMs need to know what fields to expect so they can plan downstream tool calls and extract the right data.' Without documented return types, LLMs cannot reason about what data each tool produces, breaking tool chaining and forcing unnecessary discovery calls.
Inferred effective spec: 2026-07-28+.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 59 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
Retrieve a single block by ID. Returns block type, content, and whether it has children.
Get child blocks of a page or block. This is how you read page content. Returns a paginated list of blocks.
Retrieve the bot user (integration) information for this MCP connection.
Retrieve a specific comment by ID.
Retrieve comments on a block or page.
Retrieve a data source by ID. Returns title, property schema, and timestamps.
Retrieve a database by ID. Returns property schema and metadata.
Retrieve a Notion page by ID. Returns properties, parent, timestamps, and URL. Use notion_get_block_children to read the page content.
Retrieve a specific property value from a page. Useful for paginated properties like relations or rollups.
Retrieve a specific user by ID.
List available templates for a data source.
List all users in your Notion workspace.
Move a page to a new parent page or data source.
Query a data source with filters and sorts. Supports pagination.
Query a database with optional filters and sorts.
Search pages and databases in your Notion workspace by title. Filter by object type and sort by last edited time.
Update a block's content. Send the block type key with updated data, e.g. { "paragraph": { "rich_text": [...] } }.
Update a data source title or property schema.
Update a Notion page. Change properties, icon, cover, or archive/trash status. Use block tools to update page content.
No error handling or recovery guidance. The rubric states: 'Error responses must tell the LLM what to do next' and 'Categorize errors as retryable, user-fixable, or fatal.' The server provides no mechanism to guide LLMs on error recovery (e.g., if a page lookup fails, no suggestion of fallback strategies). This violates pattern:recovery-guide.
Constraint documentation missing from parameter descriptions. The rubric requires: 'Describe the expected format, range, and allowed values directly in the parameter description.' For example, 'page_size' describes 'Results per page (max 100)' but does not specify a minimum or validate that max is enforced; 'parent' in notion_create_page shows structure in description but does not explicitly state it is one-of (data_source_id OR page_id, not both). These undocumented constraints force LLMs to guess valid input ranges.
Vague parameter descriptions for complex nested objects. 'parent' in notion_create_page is described with inline JSON structure but lacks prose explanation of when to use which variant (data_source_id for database rows, page_id for subpages). This undocumented dependency violates pattern:tool-description, 'If parameters are mutually exclusive, state this in descriptions.'
Destructive tools lack confirmation/dry-run support. notion_delete_block, notion_update_page (with archived/in_trash flags), and notion_move_page are irreversible operations. The rubric states: 'Irreversible operations should support a dry-run or confirmation step. Agents make mistakes, a confirm_before_execute pattern prevents catastrophic errors.' No such safeguard is present.
Pagination results lack total count or continuation guidance. query_database, query_data_source, notion_list_users, and similar paginated tools accept start_cursor and page_size but descriptions do not explain how to detect end-of-results or whether a next_cursor is returned. The rubric requires: 'Tools returning lists should accept page/offset and limit parameters and return a total count or next_cursor.'
Tool descriptions lack WHEN/WHY guidance. Many tools are functionally similar, notion_get_page vs notion_get_page_property, notion_query_database vs notion_search, notion_list_data_source_templates vs notion_get_data_source. Descriptions state WHAT they do but not WHEN to choose one over another. LLMs waste reasoning cycles on ambiguous selections.
notion_get_bot_user has empty inputSchema properties ({}). While the tool is defined, the empty schema is semantically unclear, does it accept NO parameters, or are parameters undocumented? This violates pattern:tool which requires explicit schema clarity.
No batch operation variants. Create/update tools accept single items. If an agent needs to create 5 pages or add 10 blocks, it must call the tool 5-10 times sequentially, wasting tokens and latency. The rubric suggests: 'Offer batch variants for tools agents call in loops.' For high-throughput scenarios, batch endpoints would improve efficiency.