Skip to main content

Notion

Connect agents to a Notion workspace: search pages and databases (optionally federating across Notion AI's connected sources), read page content, run database queries, and create or update pages and records.

Every tool type on this page requires a Notion connector — an OAuth connection to the workspace the agent should work in, scoped to the pages and databases shared with the integration. The tool config points at the connector with connectorId, and Autessa refreshes the OAuth token automatically. See Connectors for how to link a workspace.

Successful results arrive under a data key and generally contain Notion's native API objects (pages, databases, blocks), so agents can read titles, properties, and content exactly as Notion returns them. Fields ending in Json (propertiesJson, childrenJson, filterJson, sortsJson) are JSON-encoded strings passed through to the Notion API verbatim — full expressive power for agents that know Notion's schema, with convenience fields like title, plainText, and Submit Form's flat fields map covering the common cases without any raw JSON.

Search TOOLNOTION_SEARCH​

Searches the workspace by keyword. With includeConnectedSources true, the search runs through Notion AI's federated search, which can also surface results from sources connected to Notion such as Slack, Google Drive, and Jira — and falls back automatically to a plain workspace search when Notion AI is not enabled on the workspace. Otherwise (and on fallback) it is a standard Notion search over pages and databases, where filter narrows results to "page" or "database". Results come back under data in Notion's native search-result shape.

Example​

Tool config
{
  "toolType": "NOTION_SEARCH",
  "connectorId": "V1StGXR8Z5",
  "query": "@@{searchTerms}",
  "filter": "page",
  "includeConnectedSources": false
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    query
    Type
    string
    Description
    Required string value.
  • Name
    filter
    Type
    string · optional
    Description
    Optional: "page", "database", or null for both. Honored on REST fallback only.
  • Name
    includeConnectedSources
    Type
    boolean
    Description
    When true, prefer Notion AI's federated search (Slack/Drive/Jira) via MCP. Falls back automatically to workspace REST search if Notion AI isn't enabled.

Recent Updates TOOLNOTION_RECENT_UPDATES​

Returns pages and databases edited within the last days days, newest first — the tool for "what changed in the workspace this week" briefings. days defaults to 7 and is capped at 90, and filter restricts results to "page" or "database". The result's data carries the resolved days and cutoffIso, a count, and the matching items in results.

Example​

Tool config
{
  "toolType": "NOTION_RECENT_UPDATES",
  "connectorId": "V1StGXR8Z5",
  "days": 7,
  "filter": "page"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    days
    Type
    integer
    Description
    Default 7 if unset. Capped at 90 to keep paging bounded.
  • Name
    filter
    Type
    string · optional
    Description
    Optional: "page", "database", or null for both.

Fetch Page TOOLNOTION_FETCH_PAGE​

Fetches one page in full: the result's data contains the page object (metadata and properties) and, unless includeBlocks is false, a blocks array with the page's content as raw Notion block objects, assembled by following pagination up to roughly 2,000 blocks. Use it after Search or Discover Pages when the agent needs to actually read a page rather than just know it exists.

Example​

Tool config
{
  "toolType": "NOTION_FETCH_PAGE",
  "connectorId": "V1StGXR8Z5",
  "pageId": "@@{pageId}",
  "includeBlocks": true
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    pageId
    Type
    string
    Description
    Required string value.
  • Name
    includeBlocks
    Type
    boolean
    Description
    When true (default), follow paginated /blocks/{id}/children to assemble the full block tree.

Query Database TOOLNOTION_QUERY_DATABASE​

Runs a query against one database with Notion's full filter and sort syntax: filterJson and sortsJson are JSON-encoded Notion filter and sorts payloads passed through unchanged, so anything expressible in the Notion API works here. Returns a single page of up to pageSize rows (capped at 100) in Notion's native query-result shape under data, including has_more and next_cursor when more rows exist.

Example​

Tool config
{
  "toolType": "NOTION_QUERY_DATABASE",
  "connectorId": "V1StGXR8Z5",
  "databaseId": "@@{databaseId}",
  "filterJson": "{\"property\": \"Status\", \"select\": {\"equals\": \"Open\"}}",
  "sortsJson": "[{\"timestamp\": \"last_edited_time\", \"direction\": \"descending\"}]",
  "pageSize": 50
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    databaseId
    Type
    string
    Description
    Required string value.
  • Name
    filterJson
    Type
    string
    Description
    JSON-encoded Notion filter object (passthrough).
  • Name
    sortsJson
    Type
    string
    Description
    JSON-encoded sorts array (passthrough).
  • Name
    pageSize
    Type
    integer
    Description
    JSON-encoded sorts array (passthrough).

Query Data Sources TOOLNOTION_QUERY_DATA_SOURCES​

Asks Notion AI to answer a question across the workspace's connected data sources, optionally grouping results with groupBy. This capability runs exclusively through Notion's hosted AI tooling: it requires a workspace plan with Notion AI connected search (Enterprise), and on workspaces without it the tool fails with CAPABILITY_UNAVAILABLE rather than falling back. For plain workspace search, use the Search tool instead.

Example​

Tool config
{
  "toolType": "NOTION_QUERY_DATA_SOURCES",
  "connectorId": "V1StGXR8Z5",
  "query": "@@{question}",
  "groupBy": "source"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    query
    Type
    string
    Description
    Required string value.
  • Name
    groupBy
    Type
    string
    Description
    Required string value.

Discover Pages TOOLNOTION_DISCOVER_PAGES​

Enumerates the pages the connector can see — up to 100 per call — optionally narrowed by a query substring. Where Search is a question-driven lookup, Discover Pages is an inventory pass: agents use it to learn what exists in the workspace and collect page IDs before fetching, updating, or appending to specific pages.

Example​

Tool config
{
  "toolType": "NOTION_DISCOVER_PAGES",
  "connectorId": "V1StGXR8Z5",
  "query": "meeting notes"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    query
    Type
    string · optional
    Description
    Optional substring to narrow the page list.

Discover Databases TOOLNOTION_DISCOVER_DATABASES​

The database counterpart to Discover Pages: lists the databases shared with the connector (up to 100 per call), optionally narrowed by query. The returned database objects include their property schemas, which is exactly what an agent needs before building a Query Database filter or a Submit Form call.

Example​

Tool config
{
  "toolType": "NOTION_DISCOVER_DATABASES",
  "connectorId": "V1StGXR8Z5",
  "query": "@@{databaseName}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    query
    Type
    string
    Description
    Required string value.

Create Page TOOLNOTION_CREATE_PAGE​

Creates a page under an existing parent: set parentType to "page_id" for a subpage or "database_id" for a new database row. title is a convenience that fills the title property directly (for database parents it lands in the Name/Title property when one exists); propertiesJson carries a raw Notion properties object for database rows with more fields, and childrenJson seeds the page with raw Notion content blocks. The created page object comes back under data, including its new page ID.

Example​

Tool config
{
  "toolType": "NOTION_CREATE_PAGE",
  "connectorId": "V1StGXR8Z5",
  "parentId": "@@{parentPageId}",
  "parentType": "page_id",
  "title": "@@{pageTitle}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    parentId
    Type
    string
    Description
    Parent page or database ID.
  • Name
    parentType
    Type
    string
    Description
    "page_id" or "database_id".
  • Name
    title
    Type
    string
    Description
    Convenience for the page title; written into the title property.
  • Name
    propertiesJson
    Type
    string · optional
    Description
    Optional raw Notion properties object (JSON-encoded). Used when the parent is a database.
  • Name
    childrenJson
    Type
    string · optional
    Description
    Optional raw Notion children blocks array (JSON-encoded).

Update Page TOOLNOTION_UPDATE_PAGE​

Updates a page's properties and archived state. propertiesJson is a raw Notion properties object applied as-is — only the properties it names are changed — and archived moves the page to trash when true or restores it when false. This tool does not touch page content blocks; use Append Blocks to add content. The updated page object comes back under data.

Example​

Tool config
{
  "toolType": "NOTION_UPDATE_PAGE",
  "connectorId": "V1StGXR8Z5",
  "pageId": "@@{pageId}",
  "propertiesJson": "{\"Status\": {\"select\": {\"name\": \"Done\"}}}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    pageId
    Type
    string
    Description
    Required string value.
  • Name
    propertiesJson
    Type
    string
    Description
    JSON-encoded Notion properties object (passthrough).
  • Name
    archived
    Type
    boolean
    Description
    JSON-encoded Notion properties object (passthrough).

Append Blocks TOOLNOTION_APPEND_BLOCKS​

Appends content to the end of a page or block. Provide either childrenJson — a raw Notion blocks array, for full control over headings, lists, callouts, and other block types — or plainText, a convenience where each line becomes a paragraph block. One of the two is required, and childrenJson wins when both are set. parentBlockId accepts a page ID or any block ID that can hold children.

Example​

Tool config
{
  "toolType": "NOTION_APPEND_BLOCKS",
  "connectorId": "V1StGXR8Z5",
  "parentBlockId": "@@{pageId}",
  "plainText": "@@{summaryText}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    parentBlockId
    Type
    string
    Description
    Required string value.
  • Name
    childrenJson
    Type
    string
    Description
    JSON-encoded Notion children blocks array. Either this OR plainText must be set.
  • Name
    plainText
    Type
    string
    Description
    Convenience: a plain string is split into paragraph blocks.

Submit Form TOOLNOTION_SUBMIT_FORM​

Adds a row to a database from a flat map of property names to string values — no Notion property JSON required. The executor reads the database's live schema and converts each value to the property's actual type: title, rich text, number, select, multi-select (comma-separated values), checkbox, date, email, phone, and URL are all handled, and field names that no longer exist in the schema are skipped rather than failing the submission. This makes it the robust choice for intake-style workflows where users may rename or rearrange database columns. The created page object comes back under data.

Example​

Tool config
{
  "toolType": "NOTION_SUBMIT_FORM",
  "connectorId": "V1StGXR8Z5",
  "databaseId": "@@{databaseId}",
  "fields": {
    "Name": "@@{customerName}",
    "Email": "@@{customerEmail}",
    "Status": "New",
    "Tags": "inbound,website"
  }
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    databaseId
    Type
    string
    Description
    Required string value.
  • Name
    fields
    Type
    object
    Description
    Flat field map: {propertyName: stringValue}. The executor reads the live database schema to resolve each value to the appropriate property type (title / rich_text / number / select / multi_select / date / etc.).