@sperax/tool-notion

Search, read, create, and manage Notion pages and databases

Notion is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-notion

Usage

Call it directly

import { notionExecutor } from '@sperax/tool-notion';

const result = await notionExecutor.invoke('searchContent', {"filter":"page","query":"<query>"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { NotionManifest, notionExecutor } from '@sperax/tool-notion';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: NotionManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await notionExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

NotionManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-notion

API reference

searchContent

Search across the Notion workspace for pages and databases.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | filter | page | database | no | Filter by object type (page or database) | | query | string | yes | Search query string |

getPage

Get the content and properties of a Notion page.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | pageId | string | yes | The unique ID of the page |

createPage

Create a new Notion page with content blocks and properties.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | content | string | no | Page content in Markdown format (will be converted to Notion blocks) | | parentId | string | no | Parent page or database ID | | properties | object | no | Page properties (for database pages) | | title | string | yes | Page title |

updatePage

Update page properties such as title, status, or tags.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | pageId | string | yes | The ID of the page to update | | properties | object | yes | Properties to update |

deletePage

Move a page to trash. Requires user confirmation.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | pageId | string | yes | The ID of the page to delete |

listPages

List pages in a database or under a parent page.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | maxResults | integer | no | Maximum number of pages to return | | parentId | string | no | Parent page or database ID |

queryDatabase

Query a Notion database with filters and sorts.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | databaseId | string | yes | The ID of the database to query | | filter | object | no | Notion filter object | | pageSize | integer | no | Number of results per page | | sorts | array | no | Sort criteria array |

createDatabase

Create a new Notion database with property schemas.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | parentId | string | yes | Parent page ID for the database | | properties | object | yes | Database property schemas (name → type configuration) | | title | string | yes | Database title |

appendBlocks

Append content blocks to an existing page.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | content | string | yes | Content to append in Markdown format (converted to Notion blocks) | | pageId | string | yes | The ID of the page to append to |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-notion is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0