Knowledge & tools

Notion tool

The Notion tool lets an agent work in your Notion workspace - searching and reading pages and databases, creating and updating them, writing page content, and shaping database fields. It has 13 actions, and one tool configuration maps to one internal integration token.

The token is only half the setup. An integration sees nothing until you share content with it. After you paste the token, you must open each page or database the agent should use and add your integration to it (••• → Add connections). Until you do, the connection is perfectly valid but the agent can't find anything - Notion simply reports pages as "not found", even ones you're looking straight at. Sharing a top-level page cascades to everything under it, so this is usually one action, not fifty. Full steps in Sharing pages.

What it can do

Thirteen actions, in four groups:

Find - search (shared pages and databases by title), get_database, get_data_source (the schema: field names and types).
Query and read - query_data_source (filter, sort, paginate), get_page (properties), get_page_content (the body blocks).
Write pages - create_page (a database row or a sub-page, with the body written as markdown), update_page (properties), append_content (add blocks to an existing page).
Shape and organize - create_database, update_data_source (add or rename fields), delete_page, delete_block.

Three things worth knowing:

Content is written as markdown. When the agent creates a page it authors the body in markdown - headings, lists, bold - which is the natural way to write, and Notion renders it as proper blocks.
Deletes go to the trash. delete_page and delete_block move things to Notion's trash, where you can restore them from the Notion UI. They aren't permanent erasures.
Rate limit - roughly 3 requests per second on all plans. The agent paces itself accordingly.

One piece of Notion vocabulary that shows up in traces: since Notion's 2025 API change, a database holds one or more data sources, and the rows actually live in a data source. That's why you'll see the agent fetch a database, then its data source, before querying rows. It handles this on its own - you don't need to think about it.

Creating the integration

Go to notion.so/my-integrations and choose New integration. Make it an internal integration associated with your workspace - you need to be a workspace owner to create one.
Give it read, insert and update content capabilities.
Open the Configuration tab and copy the token (it starts with ntn_).
Paste the token into the Hania form and save - then do the sharing step below.

This is the step that makes everything work. A fresh integration has access to nothing at all, by design - Notion makes you grant it page by page.

Open the page or database you want the agent to use.
Click ••• in the top-right corner.
Choose Add connections and select your integration.

Sharing a top-level page cascades to everything nested under it, so the tidiest approach is to put the agent's working area under one parent page and share that once. Repeat for anything that lives outside that parent.

Notion moves its menus around occasionally, so treat the action names above as authoritative and the exact positions as approximate - if ••• isn't top-right, look for the page's overflow menu.

Field reference

Integration Token (required, secret) - an internal integration token (starts with ntn_) from notion.so/my-integrations. The pages and databases you want to use must be shared with the integration (open the page → ••• → Add connections). Stored encrypted and never returned.

Troubleshooting

The agent can't find a page or database that clearly exists - it hasn't been shared with the integration. This is far and away the most common cause. Open the page → ••• → Add connections. Notion reports this as object_not_found, which reads like the page is missing when really it's just invisible to the integration.
"unauthorized" - the token was pasted incorrectly, or the integration has been deleted. Re-copy it from the Configuration tab, or create a new integration.
429 rate limited - the roughly 3-requests-per-second cap. The agent backs off and continues.
Validation errors (a missing id or property) - the agent self-corrects these, so they may flash through a trace before the call succeeds.

Safety in autonomous runs

Like any tool, the Notion tool carries a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Because it deletes pages and blocks and can change database schema, a new configuration is created with Read-only switched off, Destructive switched on, and Sends data externally on - so destructive actions are gated in autonomous runs unless the bot's "Allow destructive actions in autonomous runs" is enabled. Deletes being recoverable from Notion's trash softens the blow, but schema changes aren't, so keep the defaults. There's also a natural extra control here: the agent can only ever touch what you've shared with the integration, so sharing narrowly is itself a safety boundary. Interactive chat is never gated by these flags.

Security

The token is stored AES-encrypted at rest and is never returned by the API - the console shows only whether a token is set. Editing a configuration without retyping the token preserves the stored one, so you must retype it to replace it. To revoke access you can delete the integration at notion.so/my-integrations, or simply remove the connection from a page to take that page out of reach.

Blueprint

The fastest way to a working Notion agent is the Notion Workspace Assistant blueprint (productivity category) - a pre-built agent for finding, reading, writing and organizing workspace content, already fluent in the database-and-data-source model. Pick it from the blueprint gallery when creating a bot; the only thing you supply is the token from this guide, plus the sharing step.