How do I use onenote-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@onenote-mcp list my notebooks" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

onenote-mcp

by jacob-hartmann

Overview Schema Related Servers Score Discussions

TypeScript

Local

OneNote MCP Server

Coverage Status CodeQL OpenSSF Scorecard npm version npm downloads License Node

A Model Context Protocol (MCP) server for Microsoft OneNote, authenticated via OAuth. Provides full read/write access to notebooks, sections, and pages through 16 tools, 5 resources, and 3 prompt templates.

Quick Start

Prerequisites

Node.js v22 or higher
A Microsoft Entra app registration with OAuth enabled
Client ID and client secret for your app registration

Step 1: Register an OAuth App

Open Microsoft Entra App registrations in Azure Portal
Create (or select) an application
Add a redirect URI: http://localhost:3000/callback
Create a client secret
Copy Application (client) ID and client secret

Step 2: Configure Your MCP Client

Claude Desktop (Recommended)

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "onenote": {
      "command": "npx",
      "args": ["-y", "onenote-mcp"],
      "env": {
        "ONENOTE_OAUTH_CLIENT_ID": "your-client-id",
        "ONENOTE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code (CLI)

{
  "mcpServers": {
    "onenote": {
      "command": "npx",
      "args": ["-y", "onenote-mcp"],
      "env": {
        "ONENOTE_OAUTH_CLIENT_ID": "your-client-id",
        "ONENOTE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "onenote": {
      "command": "npx",
      "args": ["-y", "onenote-mcp"],
      "env": {
        "ONENOTE_OAUTH_CLIENT_ID": "your-client-id",
        "ONENOTE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Step 3: First-Time Authorization

On first use, the server will:

Print an OAuth authorization URL to stderr
Wait for you to open the URL in your browser
Receive the callback at localhost
Cache tokens locally for reuse and refresh

Related MCP server: OneNote MCP Server

Transport Mode

This server uses STDIO transport exclusively.

Tools

The server exposes 16 tools for interacting with OneNote:

Tool	Description
`list-notebooks`	List all notebooks accessible to the authenticated user
`get-notebook`	Get detailed information about a specific notebook
`list-section-groups`	List section groups in a notebook or across all notebooks
`get-section-group`	Get details of a specific section group including its sections
`list-sections`	List sections in a notebook, section group, or across all notebooks
`get-section`	Get detailed information about a specific section
`create-section`	Create a new section in a notebook or section group
`list-pages`	List pages in a specific section
`get-page`	Get metadata for a specific page (title, timestamps, parent info)
`get-page-content`	Get the full HTML content of a page
`get-page-preview`	Get a short text preview of a page (up to 300 characters)
`create-page`	Create a new page in a section with HTML content
`update-page`	Update page content using JSON patch commands
`delete-page`	Permanently delete a page
`search-pages`	Search pages by keyword across titles and content
`get-notebook-hierarchy`	Get the complete notebook/section-group/section tree in one call

Resources

The server exposes 5 resources for direct data access:

Resource	URI	Description
`notebooks-list`	`onenote://notebooks`	List of all notebooks
`notebook`	`onenote://notebooks/{notebookId}`	A specific notebook with its sections and section groups
`notebook-sections`	`onenote://notebooks/{notebookId}/sections`	Sections in a specific notebook
`section-pages`	`onenote://sections/{sectionId}/pages`	Pages in a specific section
`page-content`	`onenote://pages/{pageId}`	The HTML content of a specific page

Prompts

The server includes 3 prompt templates for common workflows:

Prompt	Description
`summarize-page`	Fetch and summarize the content of a specific OneNote page
`search-notes`	Guide through a search workflow across OneNote notes
`create-note`	Guide through creating a new page in the right notebook and section

Configuration Reference

Variable	Required	Default	Description
`ONENOTE_OAUTH_CLIENT_ID`	Yes*	-	OAuth client ID
`ONENOTE_OAUTH_CLIENT_SECRET`	Yes*	-	OAuth client secret
`ONENOTE_ACCESS_TOKEN`	No	-	Manual token override (bypasses OAuth)
`ONENOTE_OAUTH_TENANT`	No	`common`	OAuth tenant selector
`ONENOTE_OAUTH_REDIRECT_URI`	No	`http://localhost:3000/callback`	OAuth callback URI
`ONENOTE_OAUTH_SCOPES`	No	`offline_access openid profile User.Read Notes.ReadWrite`	Space-delimited OAuth scopes
`ONENOTE_TOKEN_STORE_PATH`	No	platform default	Token cache file path
`ONENOTE_OAUTH_AUTHORITY_BASE_URL`	No	`https://login.microsoftonline.com`	OAuth authority base override
`ONENOTE_GRAPH_BASE_URL`	No	`https://graph.microsoft.com/v1.0`	Graph API base override

* Required unless ONENOTE_ACCESS_TOKEN is set.

Features

16 MCP tools for full OneNote read/write access (notebooks, sections, pages)
5 MCP resources for direct data access via URI templates
3 MCP prompt templates for common workflows (summarize, search, create)
OAuth authorization code flow with automatic token refresh
Secure token cache with platform-specific default locations
Microsoft Graph API client with error handling and pagination
Security hardening (CodeQL, dependency review, Scorecard, SBOM)
CI/CD with automated release and npm trusted publishing

Development

Setup

# Clone the repo
git clone https://github.com/jacob-hartmann/onenote-mcp.git
cd onenote-mcp

# Use Node.js 22
# (macOS/Linux nvm): nvm install && nvm use
# (Windows nvm-windows): nvm install 22 && nvm use 22

# Install dependencies
pnpm install

# Copy env template
cp .env.example .env

Running Locally

# Development mode (auto-reload)
pnpm dev

# Production build
pnpm build

# Production run
pnpm start

Debugging

# Run from source
pnpm inspect

# Run from built output
pnpm inspect:dist

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

Support

See SUPPORT.md.

License

MIT © Jacob Hartmann

Available Tools

16 tools

create-pageCreate PageA

Create a new page in a OneNote section. The content should be provided as HTML. The HTML must be valid XHTML with a title in the tag. At minimum, provide a title; the body can be empty for a blank page.

ParametersJSON Schema

Name	Required	Description
`title`	Yes	The title for the new page
`content`	No	HTML body content for the page. If omitted, creates a page with only the title. Do not include <html>, <head>, or <body> tags -- only the inner body content (e.g., '<p>Hello world</p>').
`sectionId`	Yes	The section ID to create the page in

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false, destructiveHint=false. The description adds behavioral context: HTML must be valid XHTML with title; body can be empty. But it does not disclose error handling, rate limits, or auth requirements beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no wasted words: purpose, HTML requirement, minimum requirement. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers parameter usages well but lacks information about the return value (what the created page object looks like). Since there is no output schema, the description should have mentioned what is returned (e.g., page ID).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: content must be valid XHTML, do not include outer tags, and title must be provided. This helps the agent use parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a new page in a OneNote section' with a specific verb and resource. It distinguishes from siblings like update-page, delete-page, etc., and specifies the content format as HTML.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use (creating a page) and specific HTML requirements (valid XHTML, title tag). However, it does not explicitly mention when not to use or provide direct alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create-sectionCreate SectionA

Create a new section. Provide notebookId to create in a notebook, or sectionGroupId to create inside a section group. Exactly one parent must be specified. Section names must be unique within the same hierarchy level, max 50 characters, and cannot contain: ? * / : < > | & # ' % ~

ParametersJSON Schema

Name	Required	Description
`notebookId`	No	ID of the notebook to create the section in
`displayName`	Yes	Name for the new section (max 50 characters)
`sectionGroupId`	No	ID of the section group to create the section in. Takes precedence over notebookId.

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant behavioral context beyond annotations: exactly one parent required, name uniqueness, max length 50, and forbidden characters. Annotations only provide readOnlyHint=false, and the description enriches the understanding of the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, no wasted words, and front-loads the purpose. It efficiently conveys all necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description is fairly complete but lacks mention of what the tool returns (e.g., the created section's ID). However, for a creation tool with clear parameters, this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning beyond the input schema by clarifying that exactly one of notebookId or sectionGroupId must be specified, and by detailing displayName constraints (uniqueness, forbidden characters) that are not in the schema properties.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a new section, specifies the two parent contexts (notebook or section group), and includes constraints. This distinguishes it from sibling tools that operate on different resources like pages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool (to create a section) and clarifies that exactly one parent must be specified. It does not explicitly mention when not to use it or provide alternatives, but the context is clear for this resource type.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete-pageDelete PageA

DestructiveIdempotent

Permanently delete a OneNote page. This action cannot be undone. The page is immediately and permanently removed.

ParametersJSON Schema

Name	Required	Description	Default
`pageId`	Yes	The unique identifier of the page to delete

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate destructiveHint=true and idempotentHint=true. Description adds permanence ('cannot be undone') and immediacy ('immediately and permanently removed'), providing context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundant information, and front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with one required parameter and no output schema. Description covers purpose and effect completely for its low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter 'pageId' is described in schema ('The unique identifier of the page to delete'). Description adds no extra parameter info but schema coverage is 100%, baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Permanently delete a OneNote page' with a specific verb and resource, distinguishing it from sibling tools like create-page or update-page.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs. alternatives (e.g., archiving or moving to recycle bin). The purpose is implied but not elaborated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-notebookGet NotebookA

Read-onlyIdempotent

Get detailed information about a specific OneNote notebook by its ID, including its sections and section groups. Use list-notebooks first to find the notebook ID.

ParametersJSON Schema

Name	Required	Description	Default
`notebookId`	Yes	The unique identifier of the notebook

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that the response includes sections and section groups, which is useful beyond annotations. No behavioral surprises implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each earning its place. The first states the core function, the second provides essential usage guidance. No extraneous text, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with a single parameter and no output schema, the description sufficiently covers what the tool does and what it returns. It could slightly improve by distinguishing from get-notebook-hierarchy, but given other context signals, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the description adds value by explaining the purpose of notebookId and explicitly telling the agent to obtain it via list-notebooks. This goes beyond the schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it retrieves detailed info about a specific notebook by ID, including sections and section groups. It distinguishes from siblings like get-notebook-hierarchy by implying a more comprehensive response, and provides a prerequisite (list-notebooks).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to use list-notebooks first to obtain the notebook ID, providing clear usage context. However, it does not mention alternatives like get-notebook-hierarchy or when to use this over other sibling tools, so slightly below maximum.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-notebook-hierarchyGet Notebook HierarchyA

Read-onlyIdempotent

Get the complete hierarchy of all notebooks, section groups, and sections. Returns a tree structure: Notebooks > Section Groups > Sections (recursively for nested section groups). This is the most efficient way to understand the user's OneNote organization.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the return format (tree structure) and efficiency, providing useful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences with no wasted words. The first sentence states the purpose, the second provides structure details, and the third adds value by highlighting efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description fully explains the return type and structure, adequate for a read-only hierarchy tool. No additional context needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters in the schema, so the description does not need to add parameter meaning. Baseline 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the complete hierarchy of notebooks, section groups, and sections, specifying the tree structure and ordering. It effectively distinguishes from sibling tools by emphasizing efficiency for understanding the user's OneNote organization.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case for full hierarchy but does not explicitly state when to use alternatives like get-notebook or list-notebooks. It provides clear context but lacks exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-pageGet PageA

Read-onlyIdempotent

Get metadata for a specific OneNote page by its ID. Returns title, timestamps, and parent info but NOT the page content. Use get-page-content to retrieve the actual HTML content.

ParametersJSON Schema

Name	Required	Description	Default
`pageId`	Yes	The unique identifier of the page

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral detail: it specifies exactly what is returned (title, timestamps, parent info) and crucially what is NOT returned (page content). This goes beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise: two sentences, no unnecessary words. The first sentence states the core purpose, and the second adds critical information about what is not included and an alternative. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description provides adequate context: it lists the returned fields (title, timestamps, parent info) and notes what is excluded. It also references the sibling for content retrieval. It is complete enough for a simple read-only tool, but could mention error scenarios or prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100% for the single parameter 'pageId', with description 'The unique identifier of the page'. The tool description does not add any additional meaning or usage details for this parameter beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets metadata for a specific OneNote page by ID, using a specific verb and resource. It distinguishes itself from the sibling 'get-page-content' by explicitly noting that it does not return page content, thus clarifying its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use this tool (to get metadata) and when not to use it (for content, use get-page-content). However, it does not contrast with other siblings like 'get-page-preview' or 'list-pages', which could provide additional guidance. The explicit alternative reference is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-page-contentGet Page ContentA

Read-onlyIdempotent

Get the full HTML content of a OneNote page. The content is returned as HTML which represents the page's text, images, tables, and formatting. Use includeIds=true if you plan to update the page afterward.

ParametersJSON Schema

Name	Required	Description	Default
`pageId`	Yes	The unique identifier of the page
`includeIds`	No	If true, includes generated element IDs needed for PATCH update operations

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds value beyond annotations by describing return format (HTML with text, images, tables, formatting) and includeIds usage. Consistent with readOnlyHint and idempotentHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: purpose, output description, usage tip. Front-loaded and to the point without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a read-only get tool: describes output format and a key parameter. No output schema, but content type is explained. Could mention error conditions, but not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers both parameters 100%. Description adds semantic value for includeIds by explaining its purpose for updates, going beyond schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'get' and resource 'full HTML content of a OneNote page'. Distinguishes from siblings like get-page and get-page-preview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to set includeIds=true (when planning to update the page). Lacks explicit when-not-to-use compared to alternatives, but still helpful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-page-previewGet Page PreviewA

Read-onlyIdempotent

Get a text preview of a OneNote page (up to 300 characters). Useful for quickly scanning page content without fetching the full HTML.

ParametersJSON Schema

Name	Required	Description	Default
`pageId`	Yes	The unique identifier of the page

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so no contradiction. The description adds the 300-character limit, but does not disclose other behaviors like output format or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (two sentences), front-loads the action, and each sentence adds value: the first defines the tool, the second explains benefit.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description could clarify the return format (e.g., a plain text string). It mentions 'text preview' but lacks specifics, making it adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the only parameter (pageId). The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Get a text preview' and specifies the resource 'OneNote page' with a character limit, distinguishing it from sibling tools like 'get-page' (full page) and 'get-page-content'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description suggests use for 'quickly scanning page content without fetching full HTML', implying context. However, it does not explicitly exclude cases or name alternatives, though siblings are listed separately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-sectionGet SectionA

Read-onlyIdempotent

Get detailed information about a specific section by its ID, including its parent notebook.

ParametersJSON Schema

Name	Required	Description	Default
`sectionId`	Yes	The unique identifier of the section

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the behavioral detail that parent notebook is included in the response, providing extra context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, front-loaded sentence with no redundant information. Every word is necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get operation with one required parameter and no output schema, the description sufficiently covers what the tool returns, including parent notebook. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description for the only parameter 'sectionId'. Description does not add additional meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'Get', the resource 'section', and specifies it returns detailed info including parent notebook. Differentiates from sibling tools like 'get-notebook' or 'list-sections'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Only implies usage for fetching a specific section by ID. No explicit guidance on when to use this versus alternative tools like 'list-sections' or 'get-page'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-section-groupGet Section GroupA

Read-onlyIdempotent

Get detailed information about a specific section group, including its sections and nested section groups.

ParametersJSON Schema

Name	Required	Description	Default
`sectionGroupId`	Yes	The unique identifier of the section group

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare read-only, idempotent, non-destructive behavior. The description adds that the tool returns detailed info including sections and nested groups, exceeding annotation scope. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy, efficiently conveys the tool's core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read operation with one parameter and no output schema, the description is adequate, clarifying return content. Could benefit from mentioning error conditions or common use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description for the single parameter. The tool description adds no additional context about the parameter, such as how to obtain the ID or expected format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Get' and resource 'section group', specifying it includes sections and nested groups. Differentiates from siblings like 'get-section' and 'list-section-groups'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving a specific section group's details but does not provide explicit guidance on when to use versus alternatives like 'list-section-groups' or 'get-section'. No when-not-to-use advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-notebooksList NotebooksA

Read-onlyIdempotent

List all OneNote notebooks accessible to the authenticated user. Returns notebook names, IDs, and metadata. Use this to discover available notebooks before accessing sections or pages.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only and idempotent. Description adds authentication context but no further behavioral traits beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, efficient, front-loaded with action. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with no output schema; description explains return values and usage context. Complete for its purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters, schema coverage is 100%. Description adds no param info, but baseline for zero params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it lists all OneNote notebooks accessible to the user, specifying return includes names, IDs, and metadata. Distinguishes from siblings by focusing on discovery before accessing sub-items.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states to use for discovering notebooks before accessing sections or pages, providing context. Does not list alternatives, but clarity is high for a simple list tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-pagesList PagesA

Read-onlyIdempotent

List pages in a specific section. Returns page titles, IDs, and metadata. Always specify a sectionId to avoid errors on accounts with many sections.

ParametersJSON Schema

Name	Required	Description	Default
`top`	No	Maximum number of pages to return (1-100, default 20)
`sectionId`	Yes	The section ID to list pages from

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns page titles, IDs, and metadata, and warns about potential errors on accounts with many sections. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff. The purpose is front-loaded, and the warning is succinct. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the description lists the return data (titles, IDs, metadata). It addresses the main risk (many sections) and is sufficient for a simple list tool with well-documented parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds minimal value beyond reinforcing the need for sectionId. It does not provide additional semantic details beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'pages', specifying the context 'in a specific section'. It distinguishes from sibling tools like search-pages and list-sections by focusing on listing within a section.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises to 'Always specify a sectionId to avoid errors', providing clear context for usage. It implies when not to use (without sectionId) but does not mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-section-groupsList Section GroupsA

Read-onlyIdempotent

List section groups. When notebookId is provided, lists section groups in that notebook. Otherwise lists all section groups across all notebooks.

ParametersJSON Schema

Name	Required	Description	Default
`notebookId`	No	Optional notebook ID to scope the listing. Omit to list all section groups.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag readOnlyHint, idempotentHint, and non-destructive. The description adds behavioral detail about conditional listing scope, which is consistent and adds value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the core action, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with one optional parameter and strong annotations, the description fully captures the behavior. No output schema needed for this read-only operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema description already explains the parameter. The tool description adds a clear conditional logic that enhances understanding beyond the standalone schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' and resource 'section groups', with conditional behavior based on notebookId. It clearly distinguishes from sibling tools like list-notebooks and list-sections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes when to use each variant (with or without notebookId), but does not explicitly state when not to use or suggest alternatives. However, the context of sibling tools makes usage clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-sectionsList SectionsA

Read-onlyIdempotent

List sections. Provide notebookId to list sections in a notebook, sectionGroupId to list sections in a section group, or omit both to list all sections across all notebooks.

ParametersJSON Schema

Name	Required	Description	Default
`notebookId`	No	Notebook ID to scope the listing
`sectionGroupId`	No	Section group ID to scope the listing. Takes precedence over notebookId if both are provided.

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds scope behavior (listing subsets) which is useful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with 'List sections', no wasted words. Each sentence adds meaningful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with two optional parameters and no output schema, the description covers all use cases. Annotations provide safety profile. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with parameter descriptions. Description adds value by explaining the combinatorial logic (omit both for all sections, precedence of sectionGroupId) beyond what schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List sections' and specifies three scoping options: by notebook, by section group, or globally. This distinguishes it from sibling tools like list-notebooks or list-pages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use each parameter (notebookId, sectionGroupId, or omit both) and notes precedence rule. Lacks explicit when-not-to-use but provides clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search-pagesSearch PagesA

Read-onlyIdempotent

Search for OneNote pages by keyword. Searches page titles and content (including OCR text from images). Optionally scope the search to a specific section. Returns matching page metadata.

ParametersJSON Schema

Name	Required	Description
`top`	No	Maximum number of results to return (1-100, default 20)
`query`	Yes	Search query string to find in page titles and content
`sectionId`	No	Optional section ID to scope the search to a specific section

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds behavioral context beyond annotations: searches OCR text from images, optional section scoping, returns metadata. Annotations already indicate read-only, idempotent, non-destructive. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first states primary purpose, second adds optional scope and output type. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes output as 'matching page metadata' but lacks specifics (e.g., fields returned). No output schema to supplement. Given search complexity and OCR detail, more output detail would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and descriptions are thorough. Description reinforces parameter intent (keyword search, optional section) but does not add new semantic meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb 'Search' and resource 'OneNote pages'. Clearly distinguishes from siblings like list-pages (which lists all pages without keyword) and get-page (specific page). Includes unique details: searches content including OCR text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use: when searching pages by keyword. Mentions optional scope to section. Does not explicitly exclude when not to use (e.g., over list-pages or get-page), but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update-pageUpdate PageA

Update the content of an existing OneNote page using JSON patch commands. Each patch specifies a target element, an action (append, insert, replace), and content. Before updating, use get-page-content with includeIds=true to get element IDs for targeting.

ParametersJSON Schema

Name	Required	Description	Default
`pageId`	Yes	The unique identifier of the page to update
`patches`	Yes	Array of patch operations to apply to the page

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are all false, so the description carries the burden. It discloses the patch-based nature and the need for element IDs, but does not mention potential side effects, failure modes, or atomicity of updates. The behavioral disclosure is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences: the first defines the purpose, and the second provides essential usage guidance. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity of patch operations and the absence of an output schema, the description should ideally mention return values or error conditions. It lacks this information, leaving the agent uncertain about the outcome. The prerequisite guidance is helpful, but the overall completeness is only adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description summarizes the patch structure (target, action, content) but adds no new information beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'update', the resource 'existing OneNote page', and the method 'using JSON patch commands'. It distinguishes this tool from siblings like 'delete-page' and 'create-page' by emphasizing modification of existing content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance to first use 'get-page-content with includeIds=true' to obtain element IDs, which is a necessary prerequisite. However, it does not explicitly state when not to use this tool or list alternative tools for other update scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation5/5

Each tool targets a distinct resource-action combination (e.g., get-page vs get-page-content vs get-page-preview) with clear descriptions that eliminate ambiguity. Slight overlap among page retrieval tools is resolved by specific content scopes.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using lowercase and hyphens (e.g., create-page, list-sections, get-notebook-hierarchy). No mixing of styles like camelCase or underscores.

Tool Count4/5

16 tools is slightly above the typical 3-15 range but still reasonable for a OneNote API surface. Each tool serves a distinct purpose, though a few (like get-page, get-page-content, get-page-preview) could be merged without loss.

Completeness3/5

Covers core operations for pages (CRUD, search, preview) and sections (list, get, create), but notable gaps exist: no create/delete for notebooks or section groups, no delete for sections, and no update for structural resources. This may force agents to use workarounds.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Jade Note
app.jadenote
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Note Taking Knowledge & Memory
2
ainote A
io.github.seunghan91
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Note Taking Developer Tools Knowledge & Memory
353
iknow
dev.iknow
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Knowledge & Memory Search Documentation Access
1
mcpOAuth
ai.zine
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Knowledge & Memory RAG Systems Autonomous Agents
2

Related MCP Servers

OneNote MCP Server
Note Taking Content Management Systems
ZubeidHendricks
A
license
Not graded
quality
D
maintenance
Enables AI language models to interact with Microsoft OneNote via a standardized interface, supporting notebook and page management through natural language.
Updated a year ago (2025-05-03 23:27 UTC)
43
26
MIT
OneNote MCP Server
Note Taking Workplace & Productivity App Automation
dcpurnell
A
license
D
quality
C
maintenance
Enables AI assistants to securely interact with Microsoft OneNote data through the Microsoft Graph API. It supports comprehensive management tasks including searching page content, creating and editing notes, and automating productivity workflows like daily note creation.
Updated a month ago (2026-07-27 11:04 UTC)
20
3
MIT
OneNote MCP Server
Note Taking Knowledge & Memory
subhamraj76
A
license
Not graded
quality
D
maintenance
Enables AI agents to read, search, write, and update Microsoft OneNote pages through the Model Context Protocol.
Updated 5 months ago (2026-03-31 21:02 UTC)
25
MIT
MCP OneNote Server
Note Taking Workplace & Productivity
FRESHSK
F
license
A
quality
F
maintenance
Enables AI agents to read, create, and analyze Microsoft OneNote notebooks, sections, and pages, including automatic image text extraction via Claude Vision.
Updated 6 months ago (2026-02-20 07:14 UTC)
7
1

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jacob-hartmann/onenote-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server