Provides full property type support for Notion database operations, including creating and updating rows with all property types, querying databases with filters and auto-pagination, appending blocks and markdown to pages, and retrieving database schemas.
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-enhanced query my Notion database named 'Tools' and list all entries"
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.
Enhanced Notion MCP server with full property type support for database operations.
Full Property Type Support: Create and update database rows with all 24 Notion property types
Auto-Pagination: Query functions automatically fetch ALL results by default (no 100-item limit)
Block Operations: Append any block type (tables, callouts, code, etc.) to pages
Markdown Conversion: Convert markdown to Notion blocks
Schema Introspection: Get database schemas with property definitions
Related MCP server: MCP Notion Server (@suncreation)
get_database_schema(database_id) - Get database schema with property types and options
query_database(database_id, filter, sorts, page_size, start_cursor, fetch_all) - Query database with filters
fetch_all=True (default): Auto-paginates to fetch ALL results
fetch_all=False: Returns single page with next_cursor for manual pagination
create_database_row(database_id, properties, content) - Create row with any property types
update_database_row(page_id, properties) - Update row properties
get_page(page_id, include_content) - Get page with properties and content (auto-paginates content blocks)
search_pages(query, filter_type, page_size, start_cursor, fetch_all) - Search pages and databases
fetch_all=True (default): Auto-paginates to fetch ALL results
fetch_all=False: Returns single page with next_cursor for manual pagination
append_blocks(page_id, blocks) - Append blocks to page
append_markdown(page_id, markdown) - Append markdown content
Type | Example Value |
title |
|
rich_text |
|
number |
|
select |
|
multi_select |
|
date |
|
checkbox |
|
url |
|
| |
phone_number |
|
status |
|
files |
|
relation |
|
people |
|
uv tool install .Add to ~/.claude.json:
{
"mcpServers": {
"notion-enhanced": {
"type": "stdio",
"command": "notion-enhanced-mcp",
"args": [],
"env": {
"NOTION_TOKEN": "your_notion_token"
}
}
}
}By default, query_database and search_pages automatically paginate through ALL results. The Notion API limits responses to 100 items per request, but this MCP handles pagination transparently.
# Fetch ALL rows (auto-pagination, default behavior)
result = query_database(database_id="abc123...")
print(f"Total tools: {result['total_count']}") # e.g., 500
# Manual pagination (for large datasets or streaming)
result = query_database(database_id="abc123...", fetch_all=False)
while result.get('has_more'):
# Process current batch
process(result['results'])
# Fetch next page
result = query_database(
database_id="abc123...",
start_cursor=result['next_cursor'],
fetch_all=False
)# Create a tool row with full properties
create_database_row(
database_id="abc123...",
properties={
"Tool Name": "Morph LLM",
"URL": "https://morphllm.com",
"Tags": ["Coding", "AI", "Developers"],
"Rating": 2,
"Description": "Fast code editing AI"
}
)Append blocks to a Notion page.
Args: page_id: The ID of the page to append to blocks: List of block objects. Each block should have: - type: Block type (paragraph, heading_1, code, table, etc.) - Additional fields depending on type: - paragraph: {"text": "content"} - heading_1/2/3: {"text": "heading"} - bulleted_list_item: {"text": "item"} - numbered_list_item: {"text": "item"} - to_do: {"text": "task", "checked": false} - code: {"code": "content", "language": "python"} - quote: {"text": "quote"} - callout: {"text": "content", "emoji": "💡"} - divider: {} (no additional fields) - bookmark: {"url": "https://..."} - image: {"url": "https://..."} - table: {"rows": [["a", "b"], ["c", "d"]], "has_column_header": true} after_block_id: Optional block ID to insert after
Returns: List of created blocks
| Name | Required | Description | Default |
|---|---|---|---|
| blocks | Yes | ||
| page_id | Yes | ||
| after_block_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It mentions that a list of created blocks is returned, but does not disclose permission requirements, append limits, idempotency, atomicity, or how the operation affects existing page content. For a mutation tool with no structured safety hints, this is a significant gap.
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 front-loaded with purpose and followed by clearly labeled Args and Returns sections. The block-type list is long but justified given the zero schema description coverage; only the Returns line is arguably redundant because an output schema exists.
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 a has-output-schema tool with three parameters and no schema descriptions, the description supplies enough parameter detail to invoke the tool correctly. Its main completeness gap is the lack of routing guidance versus append_markdown and the absence of behavioral context such as permissions or limits.
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 0%, and the description compensates thoroughly for all three parameters. It explains page_id, after_block_id, and provides a detailed enumeration of block types with required fields for each type, which is exactly the semantic detail an agent needs to construct valid calls.
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 a specific verb and resource: 'Append blocks to a Notion page.' This is clear and actionable. However, it does not distinguish itself from the sibling tool append_markdown, which also appends content to a page, leaving the agent to infer the difference between structured blocks and markdown.
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 no when-to-use guidance, no when-not-to-use guidance, and no alternatives such as append_markdown. It only lists parameters and return value, leaving the agent to infer context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append markdown content to a Notion page.
Converts markdown to Notion blocks and appends them.
Args: page_id: The ID of the page to append to markdown: Markdown content to append
Returns: Number of blocks created
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | ||
| markdown | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 does disclose the useful transformation behavior (markdown is converted to Notion blocks) and that appends are additive, but it omits permissions/auth needs, whether appending requires editor access, and error behavior. For an un-annotated mutation tool, this is a significant gap.
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?
Front-loaded one-line purpose and a concise conversion note. The Args/Returns structure is clean, though the Args section only repeats the schema and the Returns note is somewhat redundant given a full output schema exists.
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 output schema covers return values and the description correctly doesn't belabor them. But for a mutation tool with no annotations and no sibling differentiation, the definition is thin — it should state when to use this vs append_blocks and note any permission expectations.
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 0% and there are 2 required parameters, so the description must compensate. The Args block restates both parameters (page_id, markdown) but adds no format, syntax, or constraint details (e.g., page_id format, markdown dialect/supported syntax). It's the minimum viable restatement.
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?
States a specific verb (append) and resource (markdown content to a Notion page), and the conversion detail (markdown to Notion blocks). However, it doesn't distinguish from the sibling 'append_blocks' — an agent must infer the difference between appending markdown vs. blocks, which is exactly the decision point here.
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 when-to-use guidance and no mention of when to prefer append_blocks over append_markdown. The relationship to its closest sibling is left entirely unstated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a comment on a page or reply to a discussion thread.
Args: page_id: The ID of the page to comment on text: Comment text content discussion_id: Optional discussion thread ID to reply to
Returns: Created comment object
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| page_id | Yes | ||
| discussion_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it discloses only that it creates a comment and returns a comment object. It says nothing about required permissions, whether text supports mentions/markdown, whether notifications are sent, whether the operation is reversible, or what happens when discussion_id is supplied.
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?
Front-loaded purpose sentence followed by an Args/Returns block; every line corresponds to a parameter or the return. The 'Returns' line is somewhat redundant given an output schema exists, but the overall structure is tight and readable.
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?
An output schema exists, so the return value need not be explained (doing so is harmless). But for a write tool with zero annotations, the description should say more about permissions, side effects, and the page_id/discussion_id relationship before an agent could invoke it confidently.
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 0%, so the description must compensate, and it does label all three parameters meaningfully (page_id = page to comment on, text = comment content, discussion_id = thread to reply to). However, the semantics are shallow: it does not say how to obtain page_id/discussion_id, what format text accepts, or the interaction between page_id and discussion_id.
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 opens with a specific verb and resource ('Create a comment on a page or reply to a discussion thread'), and even scopes the two modes of operation. It is clear what the tool does; the only thing keeping it from a 5 is that no sibling tool covers comments, so there is nothing to be explicitly differentiated from.
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?
Usage is implied rather than stated: the phrase 'or reply to a discussion thread' hints that discussion_id selects reply mode, but the description never states when to include discussion_id versus when to omit it, nor any prerequisites (e.g., permissions on the page). No alternatives are named, which is acceptable here since no sibling does the same thing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new database (as a child of a page).
Args: parent_page_id: The ID of the parent page title: Database title properties: Database property schema. Keys are property names, values are property config objects, e.g.: {"Name": {"title": {}}, "Tags": {"multi_select": {"options": []}}}
Returns: Created database with ID and URL
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| properties | Yes | ||
| parent_page_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the created artifact and its return value but says nothing about required permissions, validation/failure behavior for a malformed property schema, or side effects of creating a child database.
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 Args/Returns structure is front-loaded and the property example earns its place by clarifying the trickiest parameter. The Returns line is slightly redundant given an output schema exists, but overall it is tight and readable.
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?
An output schema exists so return-value detail is unnecessary, and all three parameters are touched on. However, for a mutation tool with zero annotations, the absence of permission requirements and error behavior leaves the agent without the operational context it would need.
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 0%, so the description must compensate, and it does: it explains parent_page_id, title, and the non-obvious nested structure of properties with a concrete JSON example ({"Name": {"title": {}}}). This adds meaning the schema cannot convey. It loses a point only for not describing optional property config types beyond the single example.
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 a specific verb+resource ("Create a new database") and adds the scoping constraint "as a child of a page," which differentiates it from create_page and create_database_row. It stops short of naming the sibling alternatives explicitly, but an agent can tell what this tool produces.
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?
There is no guidance on when to use this versus create_page, create_database_row, or query_database. The parent-page constraint is a structural fact, not a when-to-use rule, so the agent is left to infer the scenario entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new row in a Notion database with full property type support.
Args: database_id: The ID of the Notion database properties: Dict of property_name -> value. Supported types: - title: str - rich_text: str - number: int or float - select: str (option name) - multi_select: list[str] (option names) - date: str (ISO 8601) or {"start": str, "end": str} - checkbox: bool - url: str - email: str - phone_number: str - status: str (status name) - files: list[str] (URLs) - relation: list[str] (page IDs) - people: list[str] (user IDs) content: Optional markdown content to add to the page body
Returns: Created page with ID and URL
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | ||
| properties | Yes | ||
| database_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 indicates creation and return (created page ID/URL), but does not disclose required permissions, integration access, rate limits, or error behavior; the supported-type list is parameter detail rather than behavioral disclosure.
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?
Front-loaded with a clear purpose sentence, then organized into Args and a Returns line. The property-type list is long but necessary because the schema itself has no descriptions; no fluff, and the structure aids scanning.
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 nested object parameter and 0% schema description coverage, the description supplies the essential parameter details an agent needs to call the tool. It also includes return info that the output schema already covers, but it leaves out usage context and any behavioral prerequisites, which are gaps for a write tool with no annotations.
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 0%, so the description must compensate, and it does: it describes database_id, the properties dict mapping, a comprehensive list of supported property types with value formats, and the optional markdown content parameter. This adds substantial meaning beyond the bare 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?
States a specific verb ('Create') and resource ('new row in a Notion database') and adds scope ('full property type support'). It distinguishes itself from read-oriented siblings like query_database and get_database_schema, but does not explicitly differentiate from create_page or update_database_row.
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?
Provides no when-to-use, when-not-to-use, or alternative tool guidance. The agent is left to infer that this is the tool for adding a row when a database write is needed, with no help choosing between it and siblings like create_page or append_markdown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a standalone page (not a database row).
For creating database rows, use create_database_row instead.
Args: parent_type: "page_id" or "workspace" (for top-level pages) parent_id: The ID of the parent page (ignored if workspace) title: Page title properties: Optional additional properties content: Optional markdown content for the page body
Returns: Created page with ID and URL
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| content | No | ||
| parent_id | Yes | ||
| properties | No | ||
| parent_type | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden. It discloses the standalone-vs-row semantic and that parent_id is ignored when parent_type is 'workspace', which is genuinely useful. However, it says nothing about required permissions/auth, whether creation is reversible, or rate limits for a mutating 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?
Front-loads the core definition and the routing rule, then uses tight Args/Returns headings. Every line carries information; nothing is padded.
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?
An output schema exists so return values need not be explained, and the description still sketches the return (ID and URL). For a 5-param mutating tool with zero annotations, the main gap is the absence of permission/authorization 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 0%, so the description must compensate, and it largely does: it enumerates all five params including the enum-like values for parent_type ('page_id' or 'workspace') and the conditional ignore rule for parent_id. 'properties: Optional additional properties' remains vague, which keeps this below 5.
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?
States a specific verb+resource ('Create a standalone page') and immediately distinguishes it from the database-row case, naming the sibling create_database_row. An agent can separate this from create_database_row and create_database without opening a schema.
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?
Explicitly routes to create_database_row for the contrasting case, which is the most likely confusion among siblings. It does not cover other adjacent cases (e.g. append_markdown / append_blocks for adding to an existing page), so usage context is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete (archive) a block.
Args: block_id: The ID of the block to delete
Returns: Deleted block object
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 clarifies that deletion is an archive (soft delete) rather than permanent removal, and states the return value is the deleted block object. However, it doesn't mention permissions required, whether the operation is reversible, or side effects on child blocks.
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 concise and front-loaded with the core action. The Args and Returns sections are structured but slightly redundant given the input schema exists, though it remains clear and 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?
Given the tool complexity (simple delete), lack of annotations, and presence of an output schema, the description is minimally adequate. It states the action and return value but omits important behavioral context like permissions, reversibility, and effects on child blocks, which would be helpful for safe invocation.
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 0%, so the description must compensate. It documents the single required parameter 'block_id' and its type (string), which is adequate for a one-parameter tool. The description adds the meaning of the parameter beyond the schema's bare property name.
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?
States a specific verb (delete/archive) and resource (block), and the parenthetical clarifies it's an archive operation rather than permanent deletion. However, it doesn't explicitly differentiate itself from sibling tools like update_block or move_page beyond the implied mutation.
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's no mention of prerequisites, whether the block must be empty, or what happens to child blocks. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single block by ID.
Args: block_id: The ID of the block
Returns: Block object with type and content
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it only states the return shape. It does not disclose error behavior for invalid or inaccessible IDs, permission requirements, or whether lookup is scoped to a workspace. The only behavioral signal is the word 'Retrieve,' implying a non-mutating read.
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 leading sentence is front-loaded and efficient, but the Args/Returns docstring blocks are boilerplate that partly duplicate the input and output schemas. Adequate but not tight.
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?
An output schema exists, so the Returns section is redundant and return semantics are covered elsewhere. However, for a retrieval tool with no annotations and an undocumented parameter, the definition leaves gaps around ID sourcing, block types, and failure modes.
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 0%, so the description is expected to compensate, but 'The ID of the block' merely restates the parameter name. No format, validation, or source-of-ID detail (e.g., where an agent obtains a block ID) is added.
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 first sentence states a specific verb and resource ('Retrieve a single block by ID'), which is clear and self-contained. It implicitly separates itself from get_block_children (plural/child-listing) and get_page (page-level), though it does not explicitly name those siblings.
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?
There is no guidance on when to use this tool versus alternatives like get_block_children, get_page, or query_database. The description gives no preconditions, no exclusions, and no routing hints for a tool in a crowded retrieval family.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve children blocks of a block or page.
Args: block_id: The ID of the parent block or page page_size: Number of results per page (max 100) start_cursor: Cursor for pagination fetch_all: If True, auto-paginate all children. Default True.
Returns: Dict with results list and pagination info
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | ||
| fetch_all | No | ||
| page_size | No | ||
| start_cursor | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the fetch_all default (True, auto-paginate) which is genuinely useful behavioral context. However, it does not state permissions, rate limits, ordering, or what happens with deeply nested children.
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?
Front-loaded purpose sentence followed by compact Args and Returns sections. Every line earns its place, though the Args block largely restates the schema titles with little added detail for block_id.
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?
An output schema exists, so return values needn't be detailed, and the description still summarizes them. With no annotations, the description addresses pagination and parameter defaults adequately, though it omits safety/behavioral traits.
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 0%, so the description must compensate. It documents all four parameters including the fetch_all auto-pagination semantics, which the schema's title 'Fetch All' does not explain. Minor gap: it doesn't clarify page_size interaction with fetch_all.
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?
States a specific verb and resource ('Retrieve children blocks of a block or page') and distinguishes itself from get_block (single block) by targeting children. The 'or page' phrasing is slightly loose but the scope is clear.
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 given on when to use this instead of get_block, get_page, or append_blocks. An agent gets no signal about hierarchy traversal vs single-block retrieval, which matters given the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the schema of a Notion database with all property definitions.
Args: database_id: The ID of the Notion database
Returns: Dict with database title and properties schema
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the return contents ('database title and properties schema') but says nothing about read-only semantics, permissions required, rate limits, or behavior on invalid/missing database IDs.
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?
Front-loaded single-sentence purpose followed by compact Args/Returns blocks. Efficient, though the Args/Returns sections are boilerplate Docstring scaffolding rather than earned content.
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?
An output schema exists, so the Returns paragraph is largely redundant and the description needn't explain return values. What is missing is the usage context and any behavioral caveats for a read tool that has no annotations to fall back on.
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 0%, so the description must compensate, but 'database_id: The ID of the Notion database' merely restates the parameter name. It adds no ID format detail (e.g., UUID) or examples to help the agent supply a valid value.
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?
States a specific verb+resource ('Get the schema of a Notion database') and adds scope detail ('all property definitions'). It is distinguishable from row-oriented siblings like query_database and create_database_row, though it never names an alternative to route against.
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?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer that this is a discovery step performed before reading or writing rows; nothing in the text says so.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Notion page with its properties and optionally content.
Args: page_id: The ID of the page include_content: Whether to fetch page content blocks (auto-paginates all blocks)
Returns: Page info with properties and optionally content
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | ||
| include_content | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 that include_content auto-paginates all blocks, which is useful behavioral context. However, it doesn't state permissions required, rate limits, or what happens on failure. The auto-pagination detail is a good start but insufficient for a read tool with no annotations.
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 concise and front-loaded with the core purpose. The Args and Returns sections are structured but could be more integrated. There is no wasted text, though the Returns section is somewhat redundant given the output schema exists.
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 an output schema exists, the description needn't detail return values, but it still includes a Returns section that merely restates the purpose. The description covers the parameters and a key behavioral trait (auto-pagination), but lacks usage guidelines and permissions information. For a tool with 2 parameters and no annotations, it is adequate but has clear 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 description coverage is 0%, so the schema provides no meaning beyond types. The description explains both parameters: page_id is the page ID, and include_content controls whether to fetch content blocks with auto-pagination. This adds meaning beyond the schema's bare types, but is basic and could include format expectations (e.g., page_id format).
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 a specific verb and resource: 'Get a Notion page with its properties and optionally content'. This is a clear read operation on a page, distinguishing it from block or database tools. However, it doesn't explicitly differentiate from siblings like get_block or get_block_children, which also retrieve content.
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 get_block, get_block_children, or search_pages. There are no conditions or exclusions stated to help an agent choose correctly among the many retrieval-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the bot user associated with the current token.
Returns: Bot user object with name, type, and workspace info
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the result is a bot user tied to the current auth token, which is useful, but omits any auth/permission requirements or failure modes (e.g., invalid token). No annotation contradiction.
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?
Front-loaded single sentence plus a brief Returns block. Every line earns its place; the Returns line is somewhat redundant with the output schema but is short.
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?
Output schema exists, so the description needn't enumerate return fields in depth. Given zero params and existing output schema, the description is adequately complete for a simple self-lookup, though it could note token/identity 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?
The tool takes zero parameters, so the baseline is 4. The description correctly reflects a no-argument identity lookup and the return fields, adding no misleading parameter guidance.
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?
States a specific verb (Get) and resource (the bot user associated with the current token), and distinguishes clearly from sibling user tools like get_users/get_user by scoping to 'the current token' rather than arbitrary 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?
Usage is implied: 'associated with the current token' tells the agent this is for self-identity lookup, but the description never says when to prefer this over get_user/get_users nor states any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a user by ID.
Args: user_id: The ID of the user
Returns: User object
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It says 'Returns: User object' but reveals nothing about error behavior on a missing ID, permission/auth requirements, or whether the result is cached. For a read tool with zero annotation coverage, this is thin.
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?
Very short and front-loaded, with the Args/Returns structure easy to scan. It wastes nothing, though the terse form leaves no room for needed 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?
An output schema exists, so return values are covered externally. But with zero annotations, zero schema description coverage, and no auth/error guidance, the definition is incomplete for a simple but permission-sensitive retrieval call.
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 0%, so the description must compensate, but it only restates the schema: 'user_id: The ID of the user.' No format, source, or example of the ID is given. Output schema exists, so return values needn't be explained, but the required parameter remains undescribed.
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?
States a clear verb+resource: 'Get a user by ID.' An agent can immediately distinguish this from get_users (bulk) and create/update user operations. It doesn't explicitly name siblings, but the singular 'a user by ID' delineates it from the plural get_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 when-to-use guidance, no prerequisites, no alternatives named. An agent must infer that this is the single-user fetch and get_users is the bulk variant. There is no statement of when to prefer this over search or get_self.
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 workspace.
Args: page_size: Number of results per page (max 100) start_cursor: Cursor for pagination
Returns: List of user objects
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | ||
| start_cursor | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses scope ('workspace') and return type, but says nothing about permissions required, whether pagination terminates, result ordering, or rate limits for an operation that enumerates all users.
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?
Front-loads the one-line purpose and uses an Args/Returns layout that is easy to scan. No wasted sentences, though the Returns block is redundant with the existing output schema.
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 both parameters and the operation's scope, and the output schema handles return values, so the core is present. It still lacks the pagination loop semantics and any access requirements that an agent enumerating an entire workspace would want.
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 0%, so the description must compensate. It adds a meaningful constraint ('max 100') and clarifies start_cursor is for pagination, but omits the default values and does not explain that start_cursor is null-typed on the first call.
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?
States a specific verb and resource with scope: 'List all users in the workspace.' An agent can distinguish it from the singular get_user and get_self siblings, though the description never explicitly contrasts them.
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 versus alternatives like get_user (single user) or get_self (current user), nor any prerequisites for listing the full workspace directory. Usage must be inferred from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a page to a different parent.
Args: page_id: The ID of the page to move parent_type: "page_id" or "database_id" parent_id: The ID of the new parent
Returns: Moved page info
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | ||
| parent_id | Yes | ||
| parent_type | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about permissions required, whether child blocks move with the page, reversibility, or failure modes. Only the trivial fact that it returns moved page info is stated, which the output schema already covers.
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?
Front-loads the one-line purpose before the args list; little wasted text. The 'Returns' line is redundant given the output schema but is brief and harmless.
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 output schema absolves it of explaining return values, and all parameters are named. However, for a mutation tool with no annotations, the absence of any permission, side-effect, or failure context leaves a real 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 0%, so the description must compensate; it does document all three parameters and, valuably, specifies the accepted values for parent_type ('page_id' or 'database_id'), which the schema does not encode as an enum. It stops short of explaining ID formats or validation rules.
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?
States a specific verb and resource ('Move a page') plus the scope ('to a different parent'), which is unambiguous and distinct from sibling tools like create_page or update_block. No explicit sibling differentiation is offered, but the operation is unique enough not to need it.
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 gives no when-to-use guidance, prerequisites, or alternatives (e.g., when to re-parent versus recreating a page). Usage is only implied by the verb itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query a Notion database with optional filter and sorts.
Args: database_id: The ID of the Notion database filter: Optional Notion filter object (see Notion API docs) sorts: Optional list of sort objects page_size: Number of results per page (max 100) start_cursor: Cursor for pagination (from previous query's next_cursor) fetch_all: If True, auto-paginate to fetch ALL results. If False, return single page with pagination info. Default True.
Returns: Dict with: - results: List of database rows with parsed properties - total_count: Number of results returned - has_more: Whether more results exist (only when fetch_all=False) - next_cursor: Cursor for next page (only when fetch_all=False and has_more=True)
| Name | Required | Description | Default |
|---|---|---|---|
| sorts | No | ||
| filter | No | ||
| fetch_all | No | ||
| page_size | No | ||
| database_id | Yes | ||
| start_cursor | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully explains pagination semantics and the return shape, including fetch_all behavior, but it omits permissions, read-only nature, rate limits, and error behavior.
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?
Front-loaded with a clear purpose, then structured Args and Returns sections. The Returns section may be partially redundant because an output schema exists, but the parameter explanations are necessary given the schema's lack of descriptions.
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?
For a six-parameter query tool with no annotations and an output schema, the description covers parameter meaning, pagination behavior, and return fields well enough to call it correctly. It is less complete on when to choose it over sibling tools and on operational constraints like permissions.
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 0%, so the description must compensate, and it does for all six parameters: database_id, filter, sorts, page_size max, start_cursor source, and fetch_all default/pagination effect. The filter and sorts descriptions defer to external Notion API docs rather than fully defining their structure.
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?
States a specific verb and resource ('Query a Notion database') plus the main optional refinements ('filter and sorts'). It is clearly a database-query tool, but it does not explicitly distinguish itself from siblings like search_pages or get_database_schema.
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 usage through its arguments (filter, sorts, pagination), but it never states when to use this tool versus alternatives or any prerequisites/exclusions. Guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Notion pages and databases.
Args: query: Search query filter_type: Optional filter - "page" or "database" page_size: Number of results per page (max 100) start_cursor: Cursor for pagination fetch_all: If True, auto-paginate to fetch ALL results. Default True.
Returns: Dict with: - results: List of matching pages/databases - total_count: Number of results - has_more: Whether more results exist (only when fetch_all=False) - next_cursor: Cursor for next page (only when fetch_all=False and has_more=True)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| fetch_all | No | ||
| page_size | No | ||
| filter_type | No | ||
| start_cursor | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the auto-pagination behavior of fetch_all (default True) and how has_more/next_cursor depend on fetch_all=False, which is real behavioral context. It omits auth/permission requirements and rate-limit behavior, which matter for a Notion workspace search.
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?
Purpose is front-loaded in a single line, and the Args/Returns structure is easy to scan with no filler. Slightly verbose in restating cursor/result fields, but each line is informative.
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?
An output schema exists, so the Returns block is somewhat redundant, though it clarifies the fetch_all-dependent fields. For a 5-parameter search tool with 0% schema coverage and no annotations, the description covers parameters adequately but leaves scope (workspace-wide vs filtered) and permissions unstated.
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 0%, so the description must compensate and it does provide a one-line gloss for each of the five parameters, including the important fetch_all default and page_size max of 100. The glosses are terse but cover the semantics that would otherwise be missing from 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 gives a clear verb+resource ('Search Notion pages and databases'), which is more specific than the bare tool name. It does not distinguish itself from siblings like query_database, so an agent cannot tell from the text alone when to prefer this over structured 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?
There is no explicit when-to-use/when-not-to-use guidance and no named alternatives, despite several closely related siblings (query_database, get_page). The filter_type note ('page' or 'database') hints at scope but is a parameter explanation, not usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a block's content or archive it.
Args: block_id: The ID of the block to update fields: Block fields to update. Pass the block type key with its content, e.g. {"paragraph": {"rich_text": [...]}} or {"archived": true} to archive.
Returns: Updated block object
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | ||
| block_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose the mutation/archive duality and the return value, but omits permission requirements, whether archival is reversible, and what happens to unspecified block fields — meaningful gaps for a destructive-capable write 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?
Front-loaded one-line summary, then compact Args/Returns sections. Every element is useful, though the Args/Returns template is slightly redundant given the output schema already covers returns.
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?
An output schema exists and both parameters are documented, so the core callable contract is covered. The remaining gap is behavioral (auth/permissions, reversibility of archival), which is notable given the absence of annotations.
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 0%, so the description must compensate, and it largely does: block_id is identified as the target block's ID, and fields is explained with a concrete example ('{"paragraph": {"rich_text": [...]}}' or '{"archived": true}'). This adds real meaning beyond the bare object schema, though it doesn't enumerate the valid block-type keys.
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 gives a specific verb and resource ('Update a block's content or archive it'), clearly distinguishing it from siblings such as update_database_row, delete_block, and append_blocks. It doesn't explicitly name a sibling, but the block-scoped mutation is unambiguous.
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 two usage modes (content update vs. archival) and shows the shape of each call, which hints at when to use which. However, it never states when to prefer this over delete_block or append_blocks, nor any prerequisites, so guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update properties on an existing Notion database row.
Args: page_id: The ID of the page/row to update properties: Dict of property_name -> value to update
Returns: Updated page info
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | ||
| properties | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It identifies a mutation ('Update properties') and lists arguments, but does not state permissions, reversibility, partial-update semantics, or property-value format requirements.
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 front-loaded and concise, using Args/Returns sections with no filler. The Returns line is somewhat redundant because an output schema exists, but it does not bloat the 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?
An output schema exists, so return details are unnecessary in the description. However, for a mutation tool with no annotations and 0% schema description coverage, the description omits key operational context such as permissions, partial updates, and required property value formats.
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 0%, so the description must compensate. It names both parameters and gives basic meaning (page_id = row ID, properties = property_name->value map), but does not explain nested property value shapes or required formats.
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 a specific verb+resource: 'Update properties on an existing Notion database row.' It distinguishes from create_database_row via 'existing' and from update_block via 'database row', giving an agent enough to select it correctly.
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 when-to-use, when-not-to-use, or alternative guidance is provided. It does not tell the agent when to choose this over query_database, create_database_row, or update_block.
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.
v0.2.0append_blocksappend_markdowncreate_commentcreate_databasecreate_database_rowcreate_pagedelete_blockget_blockget_block_childrenget_database_schemaget_pageget_selfget_userget_usersmove_pagequery_databasesearch_pagesupdate_blockupdate_database_rowScored across 19 tools
Most tools are clearly distinct by resource and action. Minor confusion: append_markdown vs. append_blocks both append content to a page, though one accepts markdown and the other raw blocks. get_block vs. get_block_children are distinct but related; descriptions clarify their difference.
Consistent verb_noun pattern throughout (e.g., get_database_schema, query_database, create_database_row, update_database_row, append_blocks, etc.). No mixing of conventions or ambiguous names.
19 tools for a comprehensive Notion server is reasonable, covering core operations. Slightly heavy but each tool appears to have a distinct role with minimal redundancy.
The surface covers pages, databases, blocks, users, and comments well. Missing explicit delete operations for pages/databases (only blocks can be deleted) and no update for page properties (though update_database_row exists for rows). The get_self and user tools add workspace awareness, but gaps in deletion and page updates are notable.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
MCP server for AI dialogue using various LLM models via AceDataCloud
