Notion

Notion

Available Tools

• notion_search(query?, filter_type?, page_size?): Search across all accessible pages and databases.
• query (string, optional): Search text. Empty string returns all accessible pages.
• filter_type (string, optional): "page" or "database". Use "database" to list databases.
• page_size (integer, optional, default: 10, max: 100)

• notion_fetch(page_id, include_block_ids?): Fetch a page's full content as readable markdown (metadata + all blocks in one call).
• page_id (string, required): Page or database entry ID.
• include_block_ids (boolean, optional, default: false): If true, appends each block's ID as <!-- id:... -->. Use this when you need to update a specific block with notion_update_block.
• Returns: title, URL, last-edited time, and full body as markdown.

• notion_create_page(parent_type, parent_id, title, properties_json?, content_markdown?): Create a new page.
• parent_type (string, required): "database", "page", or "workspace" (workspace root)
• parent_id (string, required): Parent UUID — ignored when parent_type="workspace"
• title (string, required): Page title
• properties_json (string, optional): Database properties as a JSON string — e.g., '{"Status": {"select": {"name": "In Progress"}}}'
• content_markdown (string, optional): Initial body content as markdown (see Markdown Support below)

• notion_update_page(page_id, properties_json, archived?): Update page properties (metadata/database fields only, not content blocks).

• notion_update_block(block_id, content_markdown): Replace the content of a specific existing block.
• block_id (string, required): Block ID — obtain via notion_fetch(include_block_ids=True)
• content_markdown (string, required): New content as a single markdown line (only the first block is used)
• page_id (string, required)
• properties_json (string, required): Properties as a JSON string
• archived (boolean, optional): true to archive, false to unarchive

• notion_append_blocks(page_id, content_markdown): Append new content blocks to the end of an existing page.
• page_id (string, required)
• content_markdown (string, required): Markdown content to append (see Markdown Support below)

Markdown Support

Both notion_create_page (content_markdown) and notion_append_blocks support:

Common Workflows

Find and read a page:

1. notion_search(query="page name") → get page id
2. notion_fetch(page_id) → read full content

Create a new page with content:

notion_create_page(
  parent_type="page",
  parent_id="<parent-page-id>",
  title="My Page",
  content_markdown="## Overview\n\nContent here..."
)

Add content to existing page:

notion_append_blocks(
  page_id="<page-id>",
  content_markdown="## New Section\n\n- Point 1\n- Point 2"
)

Edit a specific block:

1. notion_fetch(page_id, include_block_ids=True)
   → ## Old Heading  <!-- id:abc-123 -->
2. notion_update_block(block_id="abc-123", content_markdown="## New Heading")

List databases:

notion_search(filter_type="database")

Use-Case Guides

For specific workflow patterns, load the reference files:

• knowledge-capture.md — Save conversation insights, decisions, and how-to guides to Notion wikis and databases
• meeting-intelligence.md — Prepare meeting materials by gathering Notion context and creating pre-reads and agendas
• research-documentation.md — Research across Notion pages, synthesize findings, and write structured reports
• spec-to-implementation.md — Turn spec pages into implementation plans, tasks, and progress tracking

Load a reference with: skill_dispatcher("notion", reference="knowledge-capture.md")

UI Guidance (from tools-config)

Notion Tool Usage:

• notion_search: Search pages and databases. Use filter_type='database' to list databases.
• notion_fetch: Read a page's full content as markdown (metadata + all blocks in one call).
• notion_create_page: Create a new page with markdown content.
• notion_update_page: Update page properties (not content — use notion_append_blocks for content).
• notion_append_blocks: Add markdown content to an existing page.

Typical workflows:

• Find and read: notion_search → notion_fetch
• Create from scratch: notion_create_page with content_markdown
• Update content: notion_append_blocks with markdown

Markdown support in content_markdown/notion_append_blocks:

• Headings: # H1 / ## H2 / ### H3
• Lists: - bullet / 1. numbered
• To-do: - [ ] unchecked / - [x] checked
• Code: ``python ... ``
• Quote: > text
• Divider: ---
• Inline: bold, italic, code

Notion Block Types Reference

JSON examples for each block type used with notion_append_blocks.

paragraph

{
  "type": "paragraph",
  "paragraph": {
    "rich_text": [{"type": "text", "text": {"content": "Regular paragraph text."}}]
  }
}

heading_1 / heading_2 / heading_3

{
  "type": "heading_1",
  "heading_1": {
    "rich_text": [{"type": "text", "text": {"content": "Section Title"}}]
  }
}

Replace heading_1 with heading_2 or heading_3 for smaller headings.

bulleted_list_item

{
  "type": "bulleted_list_item",
  "bulleted_list_item": {
    "rich_text": [{"type": "text", "text": {"content": "Bullet point text"}}]
  }
}

numbered_list_item

{
  "type": "numbered_list_item",
  "numbered_list_item": {
    "rich_text": [{"type": "text", "text": {"content": "Numbered item text"}}]
  }
}

to_do

{
  "type": "to_do",
  "to_do": {
    "rich_text": [{"type": "text", "text": {"content": "Task description"}}],
    "checked": false
  }
}

toggle

{
  "type": "toggle",
  "toggle": {
    "rich_text": [{"type": "text", "text": {"content": "Toggle header (click to expand)"}}]
  }
}

code

{
  "type": "code",
  "code": {
    "rich_text": [{"type": "text", "text": {"content": "print('hello world')"}}],
    "language": "python"
  }
}

Supported languages include: python, javascript, java, go, rust, sql, bash, json, yaml, markdown, and many more.

quote

{
  "type": "quote",
  "quote": {
    "rich_text": [{"type": "text", "text": {"content": "Quoted text goes here."}}]
  }
}

divider

{
  "type": "divider",
  "divider": {}
}

Rich Text with Formatting

Add annotations for bold, italic, strikethrough, underline, code, and color:

{
  "type": "text",
  "text": {"content": "Bold and italic text"},
  "annotations": {
    "bold": true,
    "italic": true,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  }
}

Rich Text with Link

{
  "type": "text",
  "text": {
    "content": "Click here",
    "link": {"url": "https://example.com"}
  }
}

Knowledge Capture

Transforms conversations, discussions, and insights into structured documentation in Notion. Captures knowledge from chat context, formats it appropriately, and saves it to the right location with proper organization.

Workflow

1. Extract content to capture

From the conversation context, identify:

• Key concepts and definitions
• Decisions made and rationale
• How-to information and procedures
• Important insights or learnings
• Q&A pairs

2. Classify content type

3. Find the right destination

notion_search(query="wiki") → find wiki or knowledge base pages
notion_search(filter_type="database") → find documentation databases

Destination options:

• General wiki page — standalone knowledge article
• Project wiki — child of a project page
• Documentation database — structured docs with properties (Type, Category, Tags, Status)
• Decision log database — properties: Decision, Date, Status, Domain, Deciders
• FAQ database — properties: Question, Category, Tags, Last Reviewed

4. Create the page

notion_create_page(
  parent_type="page",          # or "database"
  parent_id="<wiki-page-id>",
  title="How to Deploy to Production",
  content_markdown="""
## Overview

Brief description of the topic.

## Prerequisites

- [ ] Required item 1
- [ ] Required item 2

## Steps

1. First step
2. Second step
3. Third step

## Related

- Link to related topic
"""
)

For database pages, include properties:

notion_create_page(
  parent_type="database",
  parent_id="<docs-db-id>",
  title="Decision: Switch to PostgreSQL",
  properties_json='{"Type": {"select": {"name": "Decision"}}, "Status": {"select": {"name": "Accepted"}}}',
  content_markdown="..."
)

5. Make content discoverable

After creating the page, link it from relevant hub pages:

notion_search(query="engineering docs index") → find the index page
notion_fetch(page_id="<index-page-id>") → read current content
notion_append_blocks(
  page_id="<index-page-id>",
  content_markdown="- [How to Deploy to Production](<new-page-url>)"
)

Tips

• Capture promptly — document while the conversation context is fresh
• Structure consistently — use the templates above for similar content types
• Search first — check if a page already exists before creating a new one
• Write for search — use clear titles and common keywords
• Add context — include why this matters and when to use it
• Link extensively — connect related knowledge for easy navigation

Common Issues

• Not sure where to save: Default to a general wiki page, easy to move later
• Content is fragmentary: Group related fragments into a cohesive document
• Already exists: Use notion_fetch to read the existing page, then notion_append_blocks to update it

Meeting Intelligence

Prepares meeting materials by gathering context from Notion, enriching with research, and creating structured meeting documents.

Workflow

1. Gather context from Notion

notion_search(query="<meeting topic>")

Look for:

• Project pages related to the meeting topic
• Previous meeting notes (for recurring meetings)
• Specifications or design docs
• Recent updates or reports
• Task/issue databases

For each relevant page:

notion_fetch(page_id="<page-id>") → extract key info

Extract:

• Project status and timeline
• Recent decisions and updates
• Open questions or blockers
• Action items from previous meetings

2. Create an internal pre-read (for the team)

notion_create_page(
  parent_type="page",
  parent_id="<project-page-id>",
  title="[Topic] - Pre-Read (Internal)",
  content_markdown="""
## Meeting Overview

- **Date**: ...
- **Attendees**: ...
- **Purpose**: ...

## Background Context

What this meeting is about and why it matters.

## Current Status

Where we are now (from Notion content).

## Key Discussion Points

- Open question 1
- Decision needed: ...

## What We Need from This Meeting

- Expected outcome 1
- Decision to make: ...
"""
)

Audience: Internal attendees only — include full context and honest assessment.

3. Create an external agenda (for all participants)

notion_create_page(
  parent_type="page",
  parent_id="<project-page-id>",
  title="[Topic] - Agenda",
  content_markdown="""
## Meeting Details

- **Date**: ...
- **Attendees**: ...

## Objective

Clear meeting goal in 1-2 sentences.

## Agenda

1. Topic 1 (10 min)
2. Topic 2 (20 min)
3. Topic 3 (15 min)

## Decisions Needed

- [ ] Decision point 1
- [ ] Decision point 2

## Action Items

*(to be filled during meeting)*

## Resources

- [Pre-Read](<pre-read-url>)
- [Project Page](<project-url>)
"""
)

Audience: All participants — professional, focused, no internal-only details.

4. Link documents to the project

notion_fetch(page_id="<project-page-id>") → find the Meetings section
notion_append_blocks(
  page_id="<project-page-id>",
  content_markdown="## Recent Meetings\n\n- [Meeting Topic - Agenda](<agenda-url>)"
)

Meeting Types

Post-Meeting Updates

After the meeting, update the agenda with:

notion_append_blocks(
  page_id="<agenda-page-id>",
  content_markdown="""
## Decisions Made

- Decision 1: ...rationale...
- Decision 2: ...rationale...

## Action Items

- [x] Owner: Task description (due: date)
- [ ] Owner: Task description (due: date)

## Key Outcomes

- Outcome 1
- Outcome 2
"""
)

Tips

• Create both documents — internal pre-read + external agenda for important meetings
• Distinguish sources — label what's from Notion vs. general knowledge
• Start with a broad search — cast a wide net, then narrow to most relevant pages
• Keep the pre-read concise — 2-3 pages maximum, even with full context
• Share early — give internal team at least 24hr to review for important meetings
• Separate internal/external — never include internal-only details in the external agenda

Research & Documentation

Search across Notion, synthesize findings from multiple pages, and create structured research reports.

Workflow

1. Search for relevant content

Cast a wide net first, then narrow:

notion_search(query="<broad topic>")
notion_search(query="<specific aspect>", filter_type="page")
notion_search(filter_type="database")  → find relevant databases

Review results for:

• Most recently edited pages (often most current)
• Pages whose titles closely match the research topic
• Databases that may contain structured data

2. Fetch and analyze pages

For each relevant page:

notion_fetch(page_id="<page-id>")

Note:

• Key findings and data points
• Timestamps (to assess recency)
• Gaps or conflicting information

3. Synthesize findings

Analyze collected information:

• Identify key themes and patterns
• Connect related concepts across sources
• Note gaps or conflicting data
• Organize findings logically

4. Create structured documentation

Choose the format based on scope:

Quick Brief (1-2 pages, fast turnaround):

notion_create_page(
  parent_type="page",
  parent_id="<research-folder-id>",
  title="Brief: <Topic>",
  content_markdown="""
## Summary

2-3 sentence overview.

## Key Findings

- Finding 1
- Finding 2
- Finding 3

## Sources

- [Page 1 Title](<url>)
- [Page 2 Title](<url>)

## Next Steps

- Action item 1
"""
)

Research Summary (3-5 pages, full analysis):

notion_create_page(
  title="Research: <Topic>",
  content_markdown="""
## Executive Summary

Key findings in 3-5 bullets.

## Background

Context and scope of research.

## Findings

### Theme 1
...

### Theme 2
...

## Analysis

Synthesis, patterns, gaps identified.

## Recommendations

1. Recommendation 1
2. Recommendation 2

## Sources

- [Source 1](<url>) — what was found
- [Source 2](<url>) — what was found

## Appendix

Raw data, additional notes.
"""
)

Comparison Report (for evaluating options):

## Options Compared

| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Cost | ... | ... | ... |
| Complexity | ... | ... | ... |

## Analysis

### Option A: Pros and Cons
...

## Recommendation

**Recommended: Option B** because...

Search Strategies

Citation Format

When referencing Notion pages in documentation:

> Source: [Page Title](<notion-url>) — last edited: <date>

Tips

• Verify recency — always check last_edited_time before citing
• Cross-reference — validate key findings across 2+ sources
• Note gaps — if information is missing or outdated, say so explicitly
• Cite sources — always link back to source pages in the report
• Separate facts from synthesis — label what came from Notion vs. your analysis

Common Issues

• No results found: Try broader search terms or different keyword combinations
• Too many results: Add filter_type="page", search for more specific terms, or query specific databases
• Conflicting information: Note the conflict explicitly and include both sources with dates

Spec to Implementation

Turns specification pages into concrete implementation plans with tasks and progress tracking.

Workflow

1. Find the specification

notion_search(query="<feature name> spec")
notion_search(query="<feature name> PRD")

If multiple results, show options to the user. If not found, ask for the page URL.

2. Fetch and analyze the spec

notion_fetch(page_id="<spec-page-id>")

Parse and extract:

• Functional requirements — user stories, feature descriptions, workflows
• Non-functional requirements — performance, security, scalability
• Acceptance criteria — testable conditions, completion definitions
• Dependencies — blockers, related systems

Note ambiguities or conflicts to address in the plan.

3. Create an implementation plan page

notion_create_page(
  parent_type="page",
  parent_id="<project-page-id>",
  title="Implementation Plan: <Feature Name>",
  content_markdown="""
## Overview

Brief description of what will be built.

**Specification**: [<Spec Title>](<spec-url>)

## Requirements Summary

### Functional
- Requirement 1
- Requirement 2

### Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Technical Approach

High-level description of the implementation strategy.

## Phases

### Phase 1: Foundation
- [ ] Task A
- [ ] Task B
- **Estimated effort**: ...

### Phase 2: Core Features
- [ ] Task C
- [ ] Task D
- **Estimated effort**: ...

### Phase 3: Testing & Polish
- [ ] Task E
- [ ] Task F

## Dependencies

- Dependency 1
- Dependency 2

## Risks

| Risk | Mitigation |
|------|-----------|
| Risk 1 | Mitigation 1 |

## Success Criteria

- [ ] Criterion 1
- [ ] Criterion 2
"""
)

4. Find a location for tasks

notion_search(query="tasks")

5. Create individual tasks

For each task in the plan:

notion_create_page(
  parent_type="page",
  parent_id="<tasks-page-id>",
  title="Implement: <Task Name>",
  content_markdown="""
## Description

What needs to be done and why.

**Implementation Plan**: [<Plan Title>](<plan-url>)
**Specification**: [<Spec Title>](<spec-url>)

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Technical Notes

Implementation approach, relevant code pointers, etc.
"""
)

6. Track progress

When starting a task:

notion_update_page(
  page_id="<task-id>",
  properties_json='{"Status": {"select": {"name": "In Progress"}}}'
)

Add progress notes:

notion_append_blocks(
  page_id="<task-id>",
  content_markdown="""
## Progress — <Date>

### Completed
- Item 1

### In Progress
- Item 2

### Blockers
- None

### Next Steps
- Next item
"""
)

When completing a task:

notion_update_page(
  page_id="<task-id>",
  properties_json='{"Status": {"select": {"name": "Done"}}}'
)

Update the implementation plan's checklist:

notion_append_blocks(
  page_id="<plan-id>",
  content_markdown="## Status Update — <Date>\n\nPhase 1 complete. Moving to Phase 2."
)

Task Breakdown Patterns

Linking Spec ↔ Implementation

• Forward link: After creating the plan, append a link to the spec page
• Backward link: Each task references both the spec and the plan
• Maintain both directions for full traceability

Common Issues

• Spec is unclear: Note ambiguities in the plan, create a "Clarification needed" task
• Requirements conflict: Document both options, create a decision task
• No tasks page found: Ask the user where to create tasks, or create them as a sub-page of the implementation plan
• Scope too large: Break into separate phases or sub-specs