notion-full-mcp

Overview Schema Source Related Servers Discussions Admin

find_replace_in_block

Destructive

Replaces specific text within a Notion block while preserving bold, italic, links, and other formatting; returns an error with current text when no match is found.

Instructions

Find and replace text within a block, preserving all formatting.

Replaces occurrences of old_text with new_text in each rich text segment while keeping bold, italic, links, and other annotations intact.

Returns an error (not a silent no-op) if old_text does not appear in the block. The error message includes the block's current plain text so the caller can diagnose Unicode / whitespace / formatting mismatches (e.g., en-dash U+2013 vs hyphen-minus U+002D, curly vs straight quotes, non-breaking space U+00A0 vs regular space). Use update_block_text or update_table_cell for full-text replacement when find/replace doesn't match because of character mismatches.

The success response includes a replacements field with the total number of occurrences of old_text that were replaced.

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": {
      "block_id": "<block_id>",
      "old_text": "<old_text>",
      "new_text": "<new_text>"
    },
    "name": "find_replace_in_block"
  }
}

Input Schema

Name	Required	Description	Default
`block_id`	Yes
`new_text`	Yes
`old_text`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1May 27, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare that this mutates data (readOnlyHint=false, destructiveHint=true); the description adds genuinely new behavior: it errors rather than silently no-op'ing on a miss, the error payload contains the block's current plain text for diagnosis, and success returns a 'replacements' count. This is exactly the context annotations cannot convey.

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 core behavior is front-loaded in the first sentence, and the failure-mode and fallback guidance follow logically. The parenthetical Unicode examples are somewhat long but earn their place by making the mismatch failure concrete.

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 three-parameter destructive text mutation, the description covers the primary behavior, the multi-segment semantics, the failure mode, the fallback tools, and the success field. An output schema exists, so the brief mention of 'replacements' is sufficient rather than redundant.

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 description coverage is 0%, so the description must carry the load. It clarifies that old_text is replaced by new_text across multiple rich text segments (implying all occurrences are replaced), which is useful, but block_id is never explained and no format expectations for old_text/new_text are given beyond the mismatch hints.

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 states a specific verb and resource ('find and replace text within a block') plus a scope qualifier ('each rich text segment'), and it names sibling tools (update_block_text, update_table_cell) as alternatives. An agent can distinguish it from generic block-update siblings without inspecting any schema.

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

Usage Guidelines5/5

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

It gives an explicit routing rule: when find/replace fails due to character mismatches (en-dash vs hyphen, curly vs straight quotes, NBSP), use update_block_text or update_table_cell instead. Both the when-to-use and when-not-to-use conditions are stated outright.

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