Skip to main content
Glama
Sign In
notion-mcp

notion-mcp

by snickery
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

notion_create_page

Create a new Notion page with optional markdown content, under a parent page or as a database row with custom properties.

Instructions

Create a new Notion page with optional markdown content.

For a standalone page under another page, provide parent_page_id. For a database row, provide database_id and properties_json.

title: the page title. content: markdown text that becomes the page body. Supports headings, lists, quotes, code blocks, inline formatting. parent_page_id: ID of the parent page. database_id: ID of a database to add the row to. properties_json: JSON object of extra Notion properties (for database rows). Keys are property names, values are Notion API property value objects. A wiki page's verification is set here too: {"Verification": {"verification": {"state": "verified"}}}. icon: an emoji ("🚀"), "custom_emoji:" (see notion_list_custom_emojis), "icon:[:]" for a native Notion icon (e.g. "icon:pizza:blue"), or an image URL. template: for database rows: "default" applies the database's default template, or pass a template ID from notion_list_templates. The template supplies the body, so leave content empty. position: where the page lands among a parent PAGE's children: "start", "end", or a block ID to insert after. silent: True skips the update, @mention and Person-property notifications this write would send. native_markdown: True sends content to Notion's own markdown parser instead of converting it to blocks here. Use it for Notion-specific markup (tables, callouts, columns, toggles, mentions) and for very large pages, which Notion then processes as a background task. markdown_version: with native_markdown, "v2" opts into Notion-flavored Markdown (a preview); default is the stable syntax.

Input Schema

NameRequiredDescriptionDefault
iconNo
titleYes
silentNo
contentNo
positionNo
templateNo
database_idNo
parent_page_idNo
native_markdownNo
properties_jsonNo
markdown_versionNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.2.2
    • addedInput schema / properties / markdown_version
      Added value: +{
+  "default": "",
+  "title": "Markdown Version",
+  "type": "string"
+}
    • addedInput schema / properties / native_markdown
      Added value: +{
+  "default": false,
+  "title": "Native Markdown",
+  "type": "boolean"
+}
    • addedInput schema / properties / position
      Added value: +{
+  "default": "",
+  "title": "Position",
+  "type": "string"
+}
    • addedInput schema / properties / silent
      Added value: +{
+  "default": false,
+  "title": "Silent",
+  "type": "boolean"
+}
    • addedInput schema / properties / template
      Added value: +{
+  "default": "",
+  "title": "Template",
+  "type": "string"
+}
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does substantial work: 'silent: True skips the update, @mention and Person-property notifications this write would send' discloses the side effect of a mutation, and 'The template supplies the body, so leave content empty' flags a destructive interaction between two parameters. 'notion then processes as a background task' for very large native pages and the '(a preview)' warning on markdown_version v2 add further behavioral context. Missing: any statement of permission/access requirements or what happens on a failed write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and the parent_page_id vs database_id fork before the parameter glossary, so an agent can decide fast and read detail only for the branch it picked. The glossary form is dense but purposeful; the only marginal line is the content-format enumeration ('headings, lists, quotes, code blocks'), which is low-value relative to the rest.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, no-annotation mutation tool this covers what an agent needs: which parameters are mutually exclusive, how template and content interact, what silent suppresses, and when to escalate to native_markdown. The presence of an output schema removes any need to describe return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

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 entirely — and it does, defining all eleven parameters with format examples: emoji literal, 'custom_emoji:<name-or-id>', 'icon:<name>[:<color>]', and 'start'/'end'/block-ID for position. It even spells out the exact properties_json shape for wiki verification, which the schema cannot convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Create a new Notion page with optional markdown content.' The two-branch routing (standalone page via parent_page_id vs database row via database_id) makes the tool's scope unambiguous. It stops short of naming the closest sibling alternatives (notion_append_content, notion_insert_page_content), so it is differentiated by implication rather than explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the selection condition between the two creation modes: 'For a standalone page under another page, provide parent_page_id' and 'For a database row, provide database_id and properties_json.' It also routes to siblings for sub-tasks (notion_list_custom_emojis for icon names, notion_list_templates for template IDs) and tells the agent when to pick native_markdown. It never says when NOT to use this tool (e.g. adding content to an existing page).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools