better-mcp-notion

write

Create or update Notion pages using Markdown with YAML frontmatter. Supports single or batch operations, appending/prepending content, and auto-matching database properties.

Instructions

Create or update Notion pages from Markdown with YAML frontmatter.

Mode (default "auto"): if frontmatter has "id" → update, otherwise → create.

Batch mode

Separate multiple pages with a line containing only "===" to create/update them in one call.

Frontmatter fields

Field	Create	Update	Description
id	-	required	Page ID to update
title	recommended	optional	Page title
parent	required*	ignored	Parent page name or ID
database	required*	ignored	Database name or ID (*either parent or database)
icon	optional	optional	Emoji (e.g. 📋) or image URL
cover	optional	optional	Cover image URL
properties	optional	optional	DB properties (see below)

Properties are auto-matched to the database schema. Use the exact property name as key. Read-only fields from read output (url, created, last_edited, formula, etc.) are safely ignored.

Examples

Create a page under a parent page:

---
title: Meeting Notes
parent: "Project Alpha"
icon: "📝"
---
## Agenda
- Review progress

Create a database entry:

---
title: Fix login bug
database: "Task Board"
properties:
  Status: In Progress
  Tags:
    - backend
    - urgent
  Due Date: "2026-03-01"
---
## Description
Login fails when password contains special chars.

Update an existing page (edit output from read):

---
id: abc123-def456
title: Updated Title
properties:
  Status: Done
---
## New content
Body replaces all existing blocks.

Append to an existing page (add content without rewriting):

Use position: "append" to add content to the end, or "prepend" to add to the beginning. Only the new content needs to be provided — existing content is preserved.

---
id: abc123-def456
---
## New section added at the end

Batch create (multiple pages in one call):

---
title: Task 1
database: "Task Board"
properties:
  Status: Todo
---
Task 1 details
===
---
title: Task 2
database: "Task Board"
properties:
  Status: Todo
---
Task 2 details

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	No	"auto" (default): create if no id, update if id present. "create": force create. "update": force update (requires id).	auto
`markdown`	Yes	Markdown with YAML frontmatter. Separate multiple pages with '===' on its own line. See tool description for format.
`position`	No	"replace" (default): replace all content. "append": add to end (efficient, no need to send existing content). "prepend": add to beginning. Only affects updates.	replace

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.3Sep 16, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this thoroughly: it explains that body content replaces existing blocks unless position is append/prepend, read-only fields are safely ignored, properties are auto-matched, and the '===' separator enables batch mode. This is far more transparency than expected for a mutation tool.

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?

The description is long but extremely well organized with headers, a frontmatter table, and multiple examples. Every section adds operational value, and the most important information (mode behavior) is front-loaded. It could be slightly trimmed without loss, but the structure supports usability well.

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 a complex tool with three parameters, no annotations, and no output schema, the description is remarkably complete. It covers all modes, batch behavior, position semantics, property handling, ignored fields, and includes practical examples. An agent has all the information needed to construct valid calls for create, update, append, and batch scenarios.

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?

Although schema description coverage is 100%, the description adds substantial meaning beyond the schema. It details the YAML frontmatter structure, the meaning of 'id', 'parent', 'database', 'icon', 'cover', and 'properties', and provides concrete examples for each mode and position. This goes well beyond the baseline of 3.

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?

The description states a clear action: 'Create or update Notion pages from Markdown with YAML frontmatter.' This names the resource, the operation, and the input format. However, it does not explicitly differentiate itself from the sibling tool 'update', and the dual create/update scope blurs the boundary somewhat, so it misses the top score for explicit sibling distinction.

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?

The description gives explicit guidance on when to create vs update based on presence of an 'id' in frontmatter, and clearly explains when to use append/prepend versus replace. It also explains batch usage. However, it does not state when to prefer this tool over sibling alternatives such as 'update' or 'read', so it lacks the 'when-not-to-use' component of a 5.

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

Deploy Server