Restore deleted Notion blocks from a Markdown backup, defaulting to the latest unrestored deletion. Use it when child pages or databases aren't involved; restore those pages separately.
Put deleted blocks back where they were (as new blocks, from the Markdown backup). Default: the latest unrestored deletion. Child pages/databases are not in the backup; use notion_restore_page for those.
| Name | Required | Description | Default |
|---|---|---|---|
| deletion_id | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does meaningful work: it discloses that restored blocks come back as NEW blocks (not the same identities) and are reconstructed from a Markdown backup, implying formatting/fidelity limits. It does not state permission requirements, whether the restore is reversible, or what happens if the same deletion is restored twice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, both front-loaded with the highest-value information (what it does, then what it does not cover). No hedging or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the action, source, default, and exclusions but omits return shape (e.g., whether created block IDs come back) and idempotency, which an agent needs to chain a restore with verification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single optional parameter, so the description must compensate, and it only partially does: it explains the default ('latest unrestored deletion') but never clarifies whether deletion_id is a deletion record identifier or a block identifier, nor its format. The default behavior is a useful addition but leaves the core identifier ambiguity unresolved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('put deleted blocks back where they were') plus the source of truth ('from the Markdown backup'), so the mechanism is unambiguous. It also names the sibling it is not for (child pages/databases) and redirects to notion_restore_page, distinguishing it from a set of 14 siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing: child pages/databases are out of scope, use notion_restore_page instead, and states the default selection when no deletion is specified. It stops short of telling the agent whether to enumerate candidates with notion_list_deletions first or what to do if the latest unrestored deletion isn't the intended one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.