notion-full-mcp

Overview Schema Source Related Servers Discussions Admin

update_page

DestructiveIdempotent

Modify a Notion page's title, icon, or database properties, or archive it by page ID. Only supplied fields change; use restore_page to unarchive.

Instructions

Update a page's title, icon, or archive status.

Only fields with non-default values are sent in the PATCH body. This tool can archive a page (archived=True) but never unarchives one; use restore_page to bring a page back from trash.

Args: page_id: The page to update. title: New title text. Omit or pass "" to leave unchanged. icon_emoji: New icon emoji. Omit or pass "" to leave unchanged. archived: Pass True to archive the page. Defaults to False (no change sent). properties_json: Optional JSON object of database properties to set. Example: {"Status": {"status": {"name": "Done"}}} Example: {"Due date": {"date": {"start": "2026-04-15"}}} Can be combined with title — both will be applied.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "page_id": "<page_id>"
    },
    "name": "update_page"
  }
}

Input Schema

Name	Required	Description	Default
`title`	No
`page_id`	Yes
`archived`	No
`icon_emoji`	No
`properties_json`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1May 27, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false; the description adds real behavioral detail beyond them: only non-default fields are included in the PATCH body, so unset values are never cleared, and archiving is one-way here. It also states that title and properties_json are applied together. What is missing is whether a partial PATCH leaves untouched fields intact forever (implied but not stated) and any permission requirements.

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?

Front-loaded with the one-way archive constraint before the parameter list, which is the right ordering for a destructive tool. The Args block is scannable and the examples earn their space. Minor redundancy: the 'Omit or pass "" to leave unchanged' phrase is repeated verbatim for both title and icon_emoji.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Combined with full per-parameter semantics and the archive/restore boundary, an agent has enough to call this correctly. Small residual gaps: no mention of permission requirements or what happens if properties_json is malformed, which matters given it is a free-form JSON string.

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?

Schema description coverage is 0%, so the description must carry the burden and it does: each of the 5 parameters is explained, including the non-obvious empty-string sentinel that means 'leave unchanged' versus omission, the False default for archived meaning 'no change sent', and two concrete properties_json examples showing nested shapes the string param must encode. This is meaning the schema cannot convey.

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

Purpose4/5

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

Opening sentence names a specific verb and resource ('Update a page') and enumerates the editable surface (title, icon, archive status). The later Args entry for properties_json adds database-property editing that the first sentence omits, so the stated scope is slightly narrower than the actual capability, but the resource is unambiguous and clearly separated from restore_page.

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 routes the inverse operation to a named sibling: 'This tool can archive a page (archived=True) but never unarchives one; use restore_page.' It also gives per-parameter usage conventions (omit or pass "" to leave unchanged). It does not mention when to prefer move_page or update_block_* for other edits, but the archive/restore boundary is the highest-risk confusion and it is handled.

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