The Notion MCP Server enables programmatic interaction with Notion workspaces via the API, optimized for LLMs through Markdown conversion to reduce token usage.
Key capabilities:
Content Operations: Read, create, update, and delete pages, blocks, and comments
Database Management: Create, query, update databases and their items with filtering and sorting options
Search Functionality: Search pages or databases by title with filtering options
User Management: List and retrieve workspace users (some features require Enterprise plan)
Response Formatting: Configure output as JSON (for programmatic access) or Markdown (for improved readability and reduced token consumption)
Advanced Configuration: Enable specific tools and troubleshoot permission issues
Referenced as a platform hosting documentation about operating Notion via Claude Desktop using MCP.
Provides conversion functionality to transform Notion API responses into Markdown format, optimizing token usage and making interactions more efficient when communicating with LLMs.
Enables interaction with Notion workspaces through API, providing tools for managing pages, databases, blocks, comments, and users. Supports creating, retrieving, updating, and querying Notion content with optional Markdown conversion to reduce context size.
Referenced as a platform hosting Japanese documentation about operating Notion via Claude Desktop using MCP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Notion MCP Server show me my latest meeting notes from the project database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Server for the Notion API, enabling LLM to interact with Notion workspaces. Additionally, it employs Markdown conversion to reduce context size when communicating with LLMs, optimizing token usage and making interactions more efficient.
Here is a detailed explanation of the steps mentioned above in the following articles:
English Version: https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
Japanese Version: https://qiita.com/suekou/items/44c864583f5e3e6325d9
Create a Notion Integration:
Visit the Notion Your Integrations page.
Click "New Integration".
Name your integration and select appropriate permissions (e.g., "Read content", "Update content").
Retrieve the Secret Key:
Copy the "Internal Integration Token" from your integration.
This token will be used for authentication.
Add the Integration to Your Workspace:
Open the page or database you want the integration to access in Notion.
Click the "···" button in the top right corner.
Click the "Connections" button, and select the the integration you created in step 1 above.
Configure Claude Desktop:
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@kimjungyeol/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": "your-integration-token"
}
}
}
}or
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["your-built-file-path"],
"env": {
"NOTION_API_TOKEN": "your-integration-token"
}
}
}
}Related MCP server: Notion MCP Server
NOTION_API_TOKEN (required): Your Notion API integration token.
NOTION_MARKDOWN_CONVERSION: Set to "true" to enable experimental Markdown conversion. This can significantly reduce token consumption when viewing content, but may cause issues when trying to edit page content.
--enabledTools: Comma-separated list of tools to enable (e.g. "notion_retrieve_page,notion_query_database"). When specified, only the listed tools will be available. If not specified, all tools are enabled.
Read-only tools example (copy-paste friendly):
node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search,notion_list_all_users,notion_retrieve_user,notion_retrieve_bot_user,notion_retrieve_commentsBy default, all responses are returned in JSON format. You can enable experimental Markdown conversion to reduce token consumption:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@kimjungyeol/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": "your-integration-token",
"NOTION_MARKDOWN_CONVERSION": "true"
}
}
}
}or
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["your-built-file-path"],
"env": {
"NOTION_API_TOKEN": "your-integration-token",
"NOTION_MARKDOWN_CONVERSION": "true"
}
}
}
}When NOTION_MARKDOWN_CONVERSION is set to "true", responses will be converted to Markdown format (when format parameter is set to "markdown"), making them more human-readable and significantly reducing token consumption. However, since this feature is experimental, it may cause issues when trying to edit page content as the original structure is lost in conversion.
You can control the format on a per-request basis by setting the format parameter to either "json" or "markdown" in your tool calls:
Use "markdown" for better readability when only viewing content
Use "json" when you need to modify the returned content
If you encounter permission errors:
Ensure the integration has the required permissions.
Verify that the integration is invited to the relevant pages or databases.
Confirm the token and configuration are correctly set in claude_desktop_config.json.
The project is organized in a modular way to improve maintainability and readability:
./
├── src/
│ ├── index.ts # Entry point and command-line handling
│ ├── client/
│ │ └── index.ts # NotionClientWrapper class for API interactions
│ ├── server/
│ │ └── index.ts # MCP server setup and request handling
│ ├── types/
│ │ ├── index.ts # Type exports
│ │ ├── args.ts # Tool argument interfaces
│ │ ├── common.ts # Common schema definitions
│ │ ├── responses.ts # API response type definitions
│ │ └── schemas.ts # Tool schema definitions
│ ├── utils/
│ │ └── index.ts # Utility functions
│ └── markdown/
│ └── index.ts # Markdown conversion utilitiesindex.ts: Application entry point. Parses command-line arguments and starts the server.
client/: Module responsible for communication with the Notion API.
index.ts: NotionClientWrapper class implements all API calls.
server/: MCP server implementation.
index.ts: Processes requests received from Claude and calls appropriate client methods.
types/: Type definition module.
index.ts: Exports for all types.
args.ts: Interface definitions for tool arguments.
common.ts: Definitions for common schemas (ID formats, rich text, etc.).
responses.ts: Type definitions for Notion API responses.
schemas.ts: Definitions for MCP tool schemas.
utils/: Utility functions.
index.ts: Functions like filtering enabled tools.
markdown/: Markdown conversion functionality.
index.ts: Logic for converting JSON responses to Markdown format.
All tools support the following optional parameter:
format (string, "json" or "markdown", default: "markdown"): Controls the response format. Use "markdown" for human-readable output, "json" for programmatic access to the original data structure. Note: Markdown conversion only works when the NOTION_MARKDOWN_CONVERSION environment variable is set to "true".
notion_append_block_children
Append child blocks to a parent block.
Required inputs:
block_id (string): The ID of the parent block.
children (array): Array of block objects to append.
Returns: Information about the appended blocks.
notion_retrieve_block
Retrieve information about a specific block.
Required inputs:
block_id (string): The ID of the block to retrieve.
Returns: Detailed information about the block.
notion_retrieve_block_children
Retrieve the children of a specific block.
Required inputs:
block_id (string): The ID of the parent block.
Optional inputs:
start_cursor (string): Cursor for the next page of results.
page_size (number, default: 100, max: 100): Number of blocks to retrieve.
Returns: List of child blocks.
notion_delete_block
Delete a specific block.
Required inputs:
block_id (string): The ID of the block to delete.
Returns: Confirmation of the deletion.
notion_retrieve_page
Retrieve information about a specific page.
Required inputs:
page_id (string): The ID of the page to retrieve.
Returns: Detailed information about the page.
notion_update_page_properties
Update properties of a page.
Required inputs:
page_id (string): The ID of the page to update.
properties (object): Properties to update.
Returns: Information about the updated page.
notion_create_database
Create a new database.
Required inputs:
parent (object): Parent object of the database.
properties (object): Property schema of the database.
Optional inputs:
title (array): Title of the database as a rich text array.
Returns: Information about the created database.
notion_query_database
Query a database.
Required inputs:
database_id (string): The ID of the database to query.
Optional inputs:
filter (object): Filter conditions.
sorts (array): Sorting conditions.
start_cursor (string): Cursor for the next page of results.
page_size (number, default: 100, max: 100): Number of results to retrieve.
Returns: List of results from the query.
notion_retrieve_database
Retrieve information about a specific database.
Required inputs:
database_id (string): The ID of the database to retrieve.
Returns: Detailed information about the database.
notion_update_database
Update information about a database.
Required inputs:
database_id (string): The ID of the database to update.
Optional inputs:
title (array): New title for the database.
description (array): New description for the database.
properties (object): Updated property schema.
Returns: Information about the updated database.
notion_create_database_item
Create a new item in a Notion database.
Required inputs:
database_id (string): The ID of the database to add the item to.
properties (object): The properties of the new item. These should match the database schema.
Returns: Information about the newly created item.
notion_search
Search pages or databases by title.
Optional inputs:
query (string): Text to search for in page or database titles.
filter (object): Criteria to limit results to either only pages or only databases.
sort (object): Criteria to sort the results
start_cursor (string): Pagination start cursor.
page_size (number, default: 100, max: 100): Number of results to retrieve.
Returns: List of matching pages or databases.
notion_list_all_users
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.
Optional inputs:
start_cursor (string): Pagination start cursor for listing users.
page_size (number, max: 100): Number of users to retrieve.
Returns: A paginated list of all users in the workspace.
notion_retrieve_user
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.
Required inputs:
user_id (string): The ID of the user to retrieve.
Returns: Detailed information about the specified user.
notion_retrieve_bot_user
Retrieve the bot user associated with the current token in Notion.
Returns: Information about the bot user, including details of the person who authorized the integration.
notion_create_comment
Create a comment in Notion.
Requires the integration to have 'insert comment' capabilities.
Either specify a parent object with a page_id or a discussion_id, but not both.
Required inputs:
rich_text (array): Array of rich text objects representing the comment content.
Optional inputs:
parent (object): Must include page_id if used.
discussion_id (string): An existing discussion thread ID.
Returns: Information about the created comment.
notion_retrieve_comments
Retrieve a list of unresolved comments from a Notion page or block.
Requires the integration to have 'read comment' capabilities.
Required inputs:
block_id (string): The ID of the block or page whose comments you want to retrieve.
Optional inputs:
start_cursor (string): Pagination start cursor.
page_size (number, max: 100): Number of comments to retrieve.
Returns: A paginated list of comments associated with the specified block or page.
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | The ID of the parent block.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| children | Yes | Array of block objects to append. Each block must follow the Notion block schema. | |
| after | No | The ID of the existing block that the new block should be appended after.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description holds full responsibility for behavioral disclosure. It mentions the requirement for insert content capabilities, which is a permission hint, but omits details about side effects, rate limits, response behavior, or failure modes. This is insufficient for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the action and key optional parameter. Every sentence earns its place without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema and many sibling tools, the description covers the core function but lacks important context such as maximum children per request, response format (though schema has a format parameter), and differentiation from sibling tools like notion_retrieve_block_children or notion_update_block. It is functional but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the description adds minimal value. It briefly mentions the 'after' parameter's purpose, but the schema already documents that. According to the baseline rule for high coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'append' and the resources 'children blocks' to a 'parent block', which accurately conveys the function. However, it does not explicitly differentiate this tool from siblings like notion_update_block or notion_retrieve_block_children, which could lead to ambiguity for an AI agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only hints at usage with 'Requires insert content capabilities' and mentions the optional 'after' parameter. There is no guidance on when to use this tool vs alternatives like notion_create_database_item (for adding to databases) or notion_update_block (for modifying block properties).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| parent | No | Parent object that specifies the page to comment on. Must include a page_id if used. | |
| discussion_id | No | The ID of an existing discussion thread to add a comment to.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| rich_text | Yes | Array of rich text objects representing the comment content. | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the creation behavior and the mutual exclusivity constraint, but does not mention side effects, authentication details beyond the capability, or return format. The basic behavior is clear but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the action, and every sentence adds essential information. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (nested rich_text objects) and the absence of an output schema, the description provides key context. It could mention the return type (created comment object), but the schema's detailed parameter documentation compensates. Overall, it is sufficiently complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. The description adds value by explicitly stating the constraint that parent and discussion_id cannot both be provided, which is a critical semantic not obvious from the schema alone. The rich_text parameter is thoroughly documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a comment in Notion' with clear verb and resource. It distinguishes between using page parent or discussion_id, and the tool name aligns with creation (unlike siblings like notion_retrieve_comments which is read-only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the 'insert comment' capability requirement and the mutual exclusivity of parent and discussion_id, guiding when to use each. However, it does not explicitly compare to other tools or state when not to use this tool, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a database in Notion
| Name | Required | Description | Default |
|---|---|---|---|
| parent | Yes | Parent object of the database | |
| title | No | Title of database as it appears in Notion. An array of rich text objects. | |
| properties | Yes | Property schema of database. The keys are the names of properties as they appear in Notion and the values are property schema objects. | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden for behavioral disclosure. It only states the purpose without revealing what the tool returns, side effects, required authentication, or constraints. The minimal text adds no transparency beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), which is appropriate but does not earn its place because it adds little to no value beyond the tool name. It could include critical usage context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, nested objects, no output schema), the description is incomplete. It lacks information about return values, error scenarios, or how the database creation interacts with Notion's hierarchy. The schema covers parameter details, but the description should provide operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-level information; all semantics are already in the input schema. The description does not enhance understanding of parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a database in Notion' clearly states the action (create) and resource (database), but does not distinguish it from sibling tools like notion_create_database_item or notion_create_comment, which also create entities. The verb+resource is specific, but differentiation is missing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool over alternatives (e.g., notion_update_database or notion_create_database_item), nor does it mention prerequisites like the parent being a page or existing database.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new item (page) in a Notion database
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | The ID of the database to add the item to.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| properties | Yes | Properties of the new database item. These should match the database schema. | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only states the creation action without mentioning side effects, required permissions, rate limits, or consequences of invalid properties. The mutation intent is implied but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy. However, it could be slightly improved by front-loading the key action and resource while being more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, nested object, no output schema), the description is incomplete. It does not mention the return value (the created page) or how to handle schema mismatches. The schema partially compensates but lacks behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the baseline is 3. The description adds no extra meaning beyond the schema; e.g., the format parameter's usage guidance is already in the schema. No new semantics are introduced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create') and the resource ('new item (page) in a Notion database'). It distinguishes from sibling tools like notion_create_database (creates whole database) and notion_update_page_properties (updates existing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No context is provided on when to use this tool versus alternatives, such as notion_update_page_properties for modifying existing items or notion_query_database for reading. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a block in Notion
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | The ID of the block to delete.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Delete a block in Notion' without any behavioral details. Since no annotations are provided, the description should disclose side effects (e.g., cascading deletion of children), required permissions, or irreversibility. It does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it is under-specified; a slightly longer description with key usage context would be more helpful without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should provide more context about the tool's behavior, such as return value or effect on related blocks. The minimal description leaves the agent underinformed for a deletion operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for its two parameters, so the schema already explains block_id format and format options. The description adds no new parameter meaning beyond the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Delete' and the resource 'block in Notion', making the action clear. However, it does not distinguish this tool from siblings like notion_update_block or notion_retrieve_block, which also operate on blocks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it relates to sibling tools like notion_append_block_children or notion_update_block.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| start_cursor | No | Pagination start cursor for listing users | |
| page_size | No | Number of users to retrieve (max 100) | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the permission requirement (Enterprise plan, Organization API key), but does not mention other behaviors like pagination flow, rate limits, or error handling. Acceptable for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines purpose, second provides critical dependency info. No redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description covers purpose and a key requirement. Lacks mention of return format or response structure, but this is not essential given the tool's straightforward nature. Could be improved slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no additional meaning beyond what the schema already provides for all three parameters. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all users in the Notion workspace,' which is a specific verb+resource combination. It distinguishes from sibling tools like 'notion_retrieve_user' (single user) and 'notion_search' (general search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a crucial usage note about requiring an Enterprise plan and Organization API key to avoid permission errors. This helps the agent know when this tool is appropriate, though it doesn't explicitly mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query a database in Notion
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | The ID of the database to query.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| filter | No | Filter conditions | |
| sorts | No | Sort conditions | |
| start_cursor | No | Pagination cursor for next page of results | |
| page_size | No | Number of results per page (max 100) | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states 'Query a database' implying a read operation, but does not disclose pagination behavior, rate limits, or that it retrieves database items rather than metadata. Minimal behavioral disclosure beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, very concise. Given that the schema covers most details, this brevity is acceptable. However, it borders on under-specification as the tool is complex.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 100% schema coverage and no output schema, the description does not explain the return structure (e.g., array of pages), pagination behavior, or the scope of query results. For a tool with 6 parameters and nested objects, the description is too sparse to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. Description adds value for the 'format' parameter by specifying when to use each format ('markdown' for reading, 'json' for writing). However, for other parameters (filter, sorts, start_cursor), the description adds nothing beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Query a database in Notion', which is a generic verb+resource. It does not specify that this tool queries items/pages within a database (as opposed to retrieving database metadata like notion_retrieve_database), nor does it differentiate from sibling tools that also interact with database items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., notion_retrieve_database for schema, notion_create_database_item for adding items). Lacks context about prerequisites or common usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a block from Notion
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | The ID of the block to retrieve.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only states 'Retrieve', implying no side effects, but does not mention authentication needs, error cases (e.g., invalid block_id), rate limits, or whether the operation is safe. Essential behavioral context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, front-loaded with the core purpose. Every word earns its place. Cannot be more concise while remaining complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description lacks information about return values or behavior. There is no output schema, so the description should at least hint at what the response contains (e.g., block content, metadata). It does not, making it incomplete for an agent that needs to use the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaningful value beyond the schema. The 'format' parameter includes a clear decision tree for when to use 'markdown' vs 'json', which helps the agent choose appropriately. The 'block_id' description specifies the expected format. This is above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'a block', which is specific enough to understand the tool's basic function. However, it does not differentiate from closely related siblings like 'notion_retrieve_block_children' or 'notion_retrieve_page', so the agent would need to infer distinctions from context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'notion_retrieve_block_children' or 'notion_retrieve_page'. There are no exclusions, prerequisites, or context hints, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the children of a block
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | The ID of the block.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| start_cursor | No | Pagination cursor for next page of results | |
| page_size | No | Number of results per page (max 100) | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully communicate behavioral traits. It only states 'retrieve' (implying read-only) but does not disclose pagination behavior, rate limits, or whether it returns multiple pages. The schema shows pagination parameters, but the description does not mention them, leaving agents to infer behavior from schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence, with no redundant information. It front-loads the core action. While brevity is valued, it could benefit from a brief note on pagination or typical use cases without becoming wordy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, no output schema, no annotations), the description is incomplete. It does not describe the return format structure (e.g., a list of block objects) or pagination behavior beyond what is hinted in the schema. For a tool used to retrieve nested content, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, including detailed guidance for each parameter (e.g., format parameter explains when to use 'json' vs 'markdown'). The tool description adds no additional parameter semantics, so it does not exceed the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('retrieve') and the resource ('children of a block'), which distinguishes it from sibling tools like 'notion_retrieve_block' (single block) and 'notion_append_block_children' (modifying children). However, it does not elaborate on what 'children' means in Notion (child blocks), which could add slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not mention that this tool is intended for retrieving hierarchical content, while 'notion_retrieve_block' is for a block's own properties. The description lacks context for preference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the bot user associated with the current token in Notion
| Name | Required | Description | Default |
|---|---|---|---|
| random_string | Yes | Dummy parameter for no-parameter tools | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It describes a read operation without side effects, but does not explicitly mention safety or other behavioral traits. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence with no redundancy, though could include more details without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not hint at the structure of the bot user object. For a simple retrieval, adequate but leaves some expectation gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. Description adds no additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action (retrieve), resource (bot user), and context (associated with current token). Distinguishes from sibling tools like notion_retrieve_user and notion_list_all_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not specify prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | The ID of the block or page whose comments you want to retrieve.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| start_cursor | No | If supplied, returns a page of results starting after the cursor. | |
| page_size | No | Number of comments to retrieve (max 100). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states it retrieves unresolved comments and requires read capabilities, but omits details such as pagination behavior, error conditions (e.g., invalid block_id), or ordering of results. These gaps limit transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core action, and contains no redundant text. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is adequate but incomplete. It defines the core functionality and a key requirement, but does not explain return values or pagination behavior, leaving some context gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, and each parameter includes helpful details (e.g., block_id formatting, format guidance). The tool description itself does not add parameter information beyond what the schema provides, so it meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves unresolved comments from a Notion page or block. The verb 'retrieve' and resource 'comments' are specific. While it does not explicitly differentiate from sibling tools like notion_retrieve_block or notion_retrieve_page, the focus on comments provides inherent distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('Requires the integration to have read comment capabilities') but does not provide guidance on when to use this tool versus alternatives. No explicit when-not or comparison to other tools is given, so usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a database in Notion
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | The ID of the database to retrieve.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose any behavioral traits beyond the verb 'retrieve', such as whether it is read-only, requires specific permissions, or returns the full database structure. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Perfectly concise for the simplicity of the tool. Front-loaded verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not provide complete context such as what exactly is retrieved (e.g., properties, items?), or how it differs from query_database. However, given the simplicity and schema coverage, it is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, providing details for both parameters. The tool description itself does not add any additional meaning beyond the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Retrieve a database') and resource ('in Notion'). However, no differentiation provided from sibling tools like 'notion_query_database', which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The format parameter description provides usage context for output format, but not for tool selection. No mention of prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a page from Notion
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | The ID of the page to retrieve.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates a read operation but omits details like permissions, rate limits, or error handling. The format parameter guidance in the schema adds some behavioral context, but the description itself adds minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence that immediately conveys the tool's core function. No extraneous words, every part is justified given that schema handles details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and sparse description: it does not explain what the returned page data contains or how to interpret it. Given sibling tools with similar retrieval operations, more context on page structure or typical use cases is needed for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any semantics beyond the schema; the schema already describes page_id format and format usage. Description provides no additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a page from Notion', specifying the verb and resource. It distinguishes from sibling tools like notion_retrieve_block or notion_retrieve_database by the resource type, though it could elaborate on what a 'page' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as notion_retrieve_block or notion_search. There's no mention of when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The ID of the user to retrieve.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It mentions the Enterprise requirement but lacks details on error handling, rate limits, or return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by a critical usage note. No extraneous words; highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks explanation of the return value (e.g., user properties) since no output schema is provided. The description is minimal but covers the essential purpose and a key prerequisite.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the input schema already clearly describes both parameters. The description adds no additional parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Retrieve a specific user by user_id in Notion.' Verb and resource are specific, and it distinguishes from sibling tools that list all users or retrieve the bot user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a crucial note about requiring an Enterprise plan and Organization API key, which guides usage. However, it does not provide explicit when-to-use or alternative comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search pages or databases by title in Notion
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Text to search for in page or database titles | |
| filter | No | Filter results by object type (page or database) | |
| sort | No | Sort order of results | |
| start_cursor | No | Pagination start cursor | |
| page_size | No | Number of results to return (max 100). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is a single sentence with no details on return format, pagination behavior, error handling, or authentication requirements. Without annotations, the description fails to disclose important behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence placed at the beginning, immediately conveying the tool's purpose without extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema covers parameters, the overall context is minimal. The description lacks scope (e.g., across which content it searches) and behavior (e.g., pagination, result size limits). It is adequate for basic understanding but leaves gaps for new users.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all parameters with clear definitions, and the 'format' parameter includes usage guidance (when to use markdown vs json). This adds concrete value beyond the schema, aiding correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches pages or databases by title in Notion. While it distinguishes the action from sibling tools like notion_retrieve_page or notion_query_database, it does not explicitly differentiate the search scope versus database querying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like notion_query_database or notion_retrieve_page. There is no mention of prerequisites, limitations, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the content of a block in Notion based on its type. The update replaces the entire value for a given field.
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | The ID of the block to update.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| block | Yes | The updated content for the block. Must match the block's type schema. | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Notes the replacement behavior ('replaces the entire value'), but with no annotations, it omits details on permissions, error conditions, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no fluff, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers basic purpose and replacement behavior but lacks details on response format, error handling, and required structure of the block object. No output schema exacerbates gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds context about 'based on its type' and 'replaces entire value', which meaningfully supplements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates block content, specifies it's type-dependent, and distinguishes from sibling tools like notion_retrieve_block and notion_delete_block.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when updating a block but provides no explicit guidance on when to use alternatives like notion_append_block_children or notion_update_page_properties.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a database in Notion
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | The ID of the database to update.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| title | No | An array of rich text objects that represents the title of the database that is displayed in the Notion UI. | |
| description | No | An array of rich text objects that represents the description of the database that is displayed in the Notion UI. | |
| properties | No | The properties of a database to be changed in the request, in the form of a JSON object. | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description is just 'Update a database in Notion'. It discloses no behavioral traits such as side effects, permissions required, or rate limits. With no annotations, the description carries the full burden but provides virtually no useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence, which is not wasteful. However, it is minimal and could include more useful information without being verbose. The brevity hinders rather than helps, as it misses key context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is severely incomplete given the tool's complexity (5 parameters, nested objects, no output schema). It fails to mention that title, description, and properties can be updated, or explain the 'format' parameter's role. The agent must rely entirely on the schema, which is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The tool description itself adds no extra meaning beyond what the schema already provides. It does not explain parameter relationships or usage nuances, but the schema is thorough, so a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a database in Notion' clearly states the verb (update) and resource (database). While it distinguishes from creation/retrieval siblings implicitly, it lacks specificity about what aspects can be updated (e.g., title, description, properties). A more descriptive sentence would improve clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives like notion_create_database or notion_retrieve_database. An agent has no context on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update properties of a page or an item in a Notion database
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | The ID of the page or database item to update.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| properties | Yes | Properties to update. These correspond to the columns or fields in the database. | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states 'update' implying mutation, but does not mention authentication requirements, rate limits, side effects, or whether the operation is reversible. This is insufficient for an update operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single sentence, concise and to the point. However, it omits some behavioral details that could be included without making it verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description does not clarify what is returned after update (e.g., the updated page object). It partially covers input via parameter semantics, but overall completeness is moderate, especially considering the complexity of updating Notion properties.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline is 3. The description adds useful context: 'properties' are likened to database columns/fields. The 'format' parameter includes explicit guidance on when to use each enum value (markdown vs json), which adds significant semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (update) and resource (properties of a page/database item). However, it does not differentiate from sibling tools like notion_update_block or notion_update_database, which also perform updates on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions. The description simply states the action without any usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
notion_append_block_childrennotion_create_commentnotion_create_databasenotion_create_database_itemnotion_delete_blocknotion_list_all_usersnotion_query_databasenotion_retrieve_blocknotion_retrieve_block_childrennotion_retrieve_bot_usernotion_retrieve_commentsnotion_retrieve_databasenotion_retrieve_pagenotion_retrieve_usernotion_searchnotion_update_blocknotion_update_databasenotion_update_page_propertiesScored across 18 tools
Most tools have distinct purposes targeting specific Notion resources (e.g., blocks, databases, pages, users, comments), with clear action differentiation. However, some overlap exists between 'notion_retrieve_block' and 'notion_retrieve_block_children' or 'notion_retrieve_database' and 'notion_query_database', which could cause minor confusion, though descriptions help clarify.
All tool names follow a consistent 'notion_verb_noun' pattern with snake_case throughout, using clear verbs like create, retrieve, update, delete, list, query, and search. This predictability makes it easy for agents to understand and select tools based on naming conventions.
With 18 tools, the count is slightly high but reasonable for a comprehensive Notion API server covering blocks, databases, pages, users, and comments. It feels slightly heavy but not excessive, as each tool serves a specific function in the domain without obvious redundancy.
The tool set provides complete CRUD/lifecycle coverage for Notion's core resources: create, retrieve, update, and delete operations for blocks, databases, pages, and comments, plus querying, searching, and user management. No significant gaps are apparent, enabling agents to handle typical Notion workflows effectively.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Connect Claude to your Platform7n workspaces — chat, links, and tasks. One-click OAuth.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
