Notion Workspace Agent Rules

Personal Profile

The profile at <a href="/ui/context.connections.profiles" class="bullet-pill"><img src="/icons/bullets/ui.svg" alt="ui" class="bullet-pill-icon" /><span class="pill-name">Connection Profiles</span></a> shows how THIS user uses Notion:

• All documents — every page and database entry they write to (not just databases)
• Topics and information — what they write about, what information they capture
• Collaboration patterns — who they work with regularly
• Writing style — how they write in Notion (captured in Writing Style)
• Quick access — IDs for fast lookups without searching

The profile is narrative-focused, describing how the person uses Notion rather than just listing databases. Use this to understand their workflow, topics of interest, and writing patterns. When they mention "my tasks" or "my project tracker", check their profile to understand their actual usage patterns before searching.

Always Use Tasks, Not Code Directly

Route through the appropriate task:

• "Find X" / "Search for" / "Where is" / "Query database" / "Show entries" / "Filter by" / "List items" → <a href="/task/notion.workspace.search" class="bullet-pill"><img src="/icons/bullets/task.svg" alt="task" class="bullet-pill-icon" /><span class="pill-name">Search Notion</span></a>
• "Create entry" / "Add to database" / "Write to" / "Write a document" / "Add page" / "Create database" / "Inline database" / "Update page" → <a href="/task/notion.workspace.write" class="bullet-pill"><img src="/icons/bullets/task.svg" alt="task" class="bullet-pill-icon" /><span class="pill-name">Write to Notion</span></a>
• "Read page" / "What's in" / "Show content of" → <a href="/task/notion.workspace.read" class="bullet-pill"><img src="/icons/bullets/task.svg" alt="task" class="bullet-pill-icon" /><span class="pill-name">Read Notion Content</span></a>

Tasks contain interpretation logic and human-friendly behavior. Calling code directly bypasses that.

Interpret Intent, Not Just Words

Users say "my tasks database" not "database ID abc123". They say "due this week" not {"property": "Due", "date": {"next_week": {}}}.

The pattern: Understand what they want → resolve IDs from <a href="/ui/context.connections.profiles" class="bullet-pill"><img src="/icons/bullets/ui.svg" alt="ui" class="bullet-pill-icon" /><span class="pill-name">Connection Profiles</span></a> → construct proper API calls.

If you can't resolve something, ask: "I found 3 databases with 'tasks' in the name. Which one?"

Database Operations

Before Querying

1. Check <a href="/ui/context.connections.profiles" class="bullet-pill"><img src="/icons/bullets/ui.svg" alt="ui" class="bullet-pill-icon" /><span class="pill-name">Connection Profiles</span></a> for known database IDs
2. If not found, search for it first with <a href="/code/notion.workspace.search" class="bullet-pill"><img src="/icons/bullets/code.svg" alt="code" class="bullet-pill-icon" /><span class="pill-name">Search Notion Workspace</span></a>
3. Cache newly discovered databases in the workspace file

Property Mapping

Users describe properties naturally. Map them:

• "status is done" → Status property equals "Done"
• "tagged with urgent" → Multi-select contains "urgent"
• "due this week" → Date property within next 7 days
• "assigned to me" → People property contains current user

When property names are ambiguous, state your assumption: "Filtering by the 'Status' property—let me know if you meant something else."

Pagination

Notion returns max 100 items per request. For larger queries:

• Fetch with pagination automatically
• Report total count: "Found 247 entries, showing first 50"
• Offer to continue: "Want me to load more?"

Creating Content

Database Entries

1. Identify target database (search if needed)
2. Map user's input to database properties
3. For missing required properties, ask or use sensible defaults
4. After creation, confirm with the new entry's title and URL

Pages with Blocks

Build rich content when appropriate:

• Meeting notes → headings + bullet lists
• Documentation → headings + paragraphs + code blocks
• Task descriptions → checkboxes + callouts for important notes

Refer to <a href="/slice/notion.workspace.reference" class="bullet-pill"><img src="/icons/bullets/slice.svg" alt="slice" class="bullet-pill-icon" /><span class="pill-name">Notion API Reference</span></a> for block construction.

Inline Databases in Pages

Inline databases cannot be created as blocks during page creation. Use this two-step workflow:

1. Create the page first with parentType: page or database
2. Then call <a href="/code/notion.workspace.write" class="bullet-pill"><img src="/icons/bullets/code.svg" alt="code" class="bullet-pill-icon" /><span class="pill-name">Create/Update Notion Content</span></a> again with parentType: inline_database using the new page's ID

Critical: Always use the provided scripts for inline databases. The script sets is_inline: true which embeds the database in the page. Writing custom API code without this flag creates a full-page database that's merely linked—not embedded.

Never bypass the scripts with raw fetch calls. The scripts handle flags and formatting that are easy to miss.

Reading Content

Extract the useful parts:

• For databases: Show properties in a readable table format
• For pages: Summarize structure, surface key content
• Don't dump raw block arrays at users

When content is long, summarize first: "This page has 3 sections: Overview, Requirements, and Timeline. Want the full content or a specific section?"

Error Handling

Common issues and responses:

• Page not shared with integration: "I can't access that page. Make sure it's shared with the Notion integration."
• Database not found: "Couldn't find a database called X. Want me to search your workspace?"
• Invalid property value: "The Status property doesn't have an option called 'Completed'. Available options are: To Do, In Progress, Done."

Rate Limits

Notion allows 3 requests/second average. The code handles this, but for large operations, warn users: "Updating 50 entries—this'll take about 20 seconds."

Understanding User's Notion Usage

The profile at <a href="/ui/context.connections.profiles" class="bullet-pill"><img src="/icons/bullets/ui.svg" alt="ui" class="bullet-pill-icon" /><span class="pill-name">Connection Profiles</span></a> is built during setup by analyzing ALL documents the user writes to—both database entries and standalone pages. It captures:

• Document patterns — how many documents, mix of databases vs pages, activity levels
• Topics — what information and topics they write about
• Collaboration — who they work with frequently
• Writing style — tone, formality, structure patterns (also saved to <a href="/ui/context.user.writing_style" class="bullet-pill"><img src="/icons/bullets/ui.svg" alt="ui" class="bullet-pill-icon" /><span class="pill-name">Writing Style</span></a>)

Always check the profile before searching. The profile tells you HOW this specific user uses Notion, not just what databases exist. Use it to understand their workflow, what they care about, and how they organize information.

When you discover new patterns or frequently-used databases/pages, the profile will be updated on the next setup run to reflect their actual usage.