notion

name	notion
description	Read, search, write, and update pages and databases in the user's Notion workspace.
scope	agent
requires	["notion"]

Typical flows:

Summarise a page → notion_search (by title) → notion_read_page (on the result's ID) → condense → report back inline. Only write a new page if the user asked you to persist the summary.

Create a page (default) → call notion_create_page with just title and optional content. Do NOT pass parent_id. The server places it under the user's default save location.

Reporting rules for create:

• Read parent_used.title from the response and mention it ONCE, briefly: "Created under 'Vela'." or similar. Do not repeat the location in a second sentence.
• Do NOT mention the Connections panel, changing the default save location, or anything about settings — unless the response includes a first_use_note string. If first_use_note is present, include that note verbatim (one time only). If it's null/absent, say nothing about settings.
• After the first creation, the server will stop sending first_use_note — so stop mentioning it. Never re-surface the tip on subsequent creates.

Create a page at a specific location → only when the user explicitly names a location. Call notion_list_accessible_pages → present the options to the user → call notion_create_page with the chosen parent_id.

Append to an existing page → when the user wants to add to a page they already have, not create a new one. notion_search (if you don't know the page_id) → notion_append_to_page with page_id and content. Don't fall back to notion_create_page unless the user explicitly asks for a new page.

Delete a block from a page → notion_read_page to list the page's blocks and find the one the user is referring to (match by text content) → confirm the target with the user if there's any ambiguity → notion_delete_block with that block_id. Never delete blocks speculatively — always identify the exact block first.

Page metadata vs body → notion_read_page returns block children (the body text). notion_get_page returns title, properties, parent, archived flag. Pick the one that answers the user's question — don't call both.

Rename / update / archive a page → if unsure of the current state, notion_get_page first. Then notion_update_page with only the fields you're changing:

• Rename: properties: { title: { title: [{ text: { content: "New name" } }] } }
• Archive: archived: true (reversible — false to restore). Confirm with the user before archiving.
• Database row fields: match the schema returned by notion_get_database.

Query a database → notion_search to locate the DB → notion_get_database to see its property names and types → notion_query_database with a filter matching the user's intent. Present the results as a compact list or table keyed on the most relevant properties — don't dump raw property JSON.

Find information → notion_search first. Do not guess page IDs — they are UUIDs, not titles.

Never use notion_search just to find a parent for a new page — that's what notion_list_accessible_pages is for, and it's usually unnecessary because the default save location handles it.

Notion returns raw block JSON from notion_read_page and raw property JSON from notion_get_page/notion_query_database. Convert to plain prose before showing the user.