| name | managing-notion |
| description | Notion workspace management - pages, databases, blocks, and content. Use when searching, creating, updating, or organizing Notion content. |
| connection_type | notion |
| preload | false |
Managing Notion
Tools for Notion workspace management including pages, databases (data sources), blocks, and comments.
Important: All tools require a parameter object. Pass {} for tools with no required parameters.
Tools (21 total)
Users
| Tool | Description |
|---|
APIGetSelf({}) | Get current bot user |
APIGetUser({ user_id }) | Get a user by ID |
APIGetUsers({}) | List all users (optional: start_cursor, page_size) |
Search
| Tool | Description |
|---|
APIPostSearch({}) | Search pages/databases by title (optional: query, filter, sort, start_cursor, page_size) |
Pages
| Tool | Description |
|---|
APIRetrieveAPage({ page_id }) | Get page metadata (optional: filter_properties) |
APIPostPage({ parent, properties }) | Create new page (optional: children, icon, cover) |
APIPatchPage({ page_id }) | Update page (optional: properties, archived, in_trash, icon, cover) |
APIMovePage({ page_id, parent }) | Move page to new parent |
APIRetrieveAPageProperty({ page_id, property_id }) | Get specific property value |
Blocks
| Tool | Description |
|---|
APIRetrieveABlock({ block_id }) | Get block metadata |
APIGetBlockChildren({ block_id }) | List child blocks (optional: start_cursor, page_size) |
APIPatchBlockChildren({ block_id, children }) | Append blocks (optional: after) |
APIUpdateABlock({ block_id }) | Update block (optional: type, archived) |
APIDeleteABlock({ block_id }) | Delete/trash a block |
Data Sources (Databases)
| Tool | Description |
|---|
APIQueryDataSource({ data_source_id }) | Query with filters (optional: filter, sorts, start_cursor, page_size) |
APIRetrieveADataSource({ data_source_id }) | Get database schema |
APICreateADataSource({ parent, properties }) | Create database (optional: title) |
APIUpdateADataSource({ data_source_id }) | Update schema (optional: title, description, properties) |
APIListDataSourceTemplates({ data_source_id }) | List templates in database |
Comments
| Tool | Description |
|---|
APIRetrieveAComment({ block_id }) | Get comments (optional: start_cursor, page_size) |
APICreateAComment({ parent, rich_text }) | Add comment |
Examples
Search and Retrieve
import { APIPostSearch, APIRetrieveAPage, APIGetBlockChildren } from '@connections/notion';
const results = await APIPostSearch({
query: 'meeting notes',
filter: { property: 'object', value: 'page' }
});
const page = await APIRetrieveAPage({ page_id: 'page-id-here' });
const blocks = await APIGetBlockChildren({ block_id: page.id });
Create Page
import { APIPostPage } from '@connections/notion';
const page = await APIPostPage({
parent: { page_id: 'parent-page-id' },
properties: {
title: [{ text: { content: 'New Page' } }]
},
children: [
{
object: 'block',
type: 'paragraph',
paragraph: { rich_text: [{ text: { content: 'Hello' } }] }
}
]
});
Query Database
import { APIQueryDataSource } from '@connections/notion';
const results = await APIQueryDataSource({
data_source_id: 'database-id',
filter: {
property: 'Status',
status: { equals: 'In Progress' }
},
sorts: [{ property: 'Due Date', direction: 'ascending' }]
});
Property Types
| Type | Format |
|---|
| Title | { title: [{ text: { content: 'value' } }] } |
| Rich Text | { rich_text: [{ text: { content: 'value' } }] } |
| Number | { number: 42 } |
| Select | { select: { name: 'Option' } } |
| Multi-select | { multi_select: [{ name: 'Tag' }] } |
| Status | { status: { name: 'Done' } } |
| Date | { date: { start: '2024-01-01' } } |
| Checkbox | { checkbox: true } |
Block Types
paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, to_do, toggle, code, quote, callout, divider, table, image, video, file
Common Errors
| Error | Solution |
|---|
| "object not found" | Verify ID is correct and accessible |
| "validation_error" | Check property names match schema |
| "unauthorized" | Ensure integration has access |
| 422 | Pass {} for tools with no required params |
Output Format
Present results as a structured report:
Managing Notion Report
══════════════════════
Resources discovered: [count]
Resource Status Key Metric Issues
──────────────────────────────────────────────
[name] [ok/warn] [value] [findings]
Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]
Target ≤50 lines of output. Use tables for multi-resource comparisons.
Anti-Hallucination Rules
- NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
- NEVER fabricate metric names or dimensions — verify against the service documentation or
--help output.
- NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
- ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
- ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.
Counter-Rationalizations
| Shortcut | Counter | Why |
|---|
| "I'll skip discovery and check known resources" | Always run Phase 1 discovery first | Resource names change, new resources appear — assumed names cause errors |
| "The user only asked for a quick check" | Follow the full discovery → analysis flow | Quick checks miss critical issues; structured analysis catches silent failures |
| "Default configuration is probably fine" | Audit configuration explicitly | Defaults often leave logging, security, and optimization features disabled |
| "Metrics aren't needed for this" | Always check relevant metrics when available | API/CLI responses show current state; metrics reveal trends and intermittent issues |
| "I don't have access to that" | Try the command and report the actual error | Assumed permission failures prevent useful investigation; actual errors are informative |
