Apache Zeppelin MCP Server

edit_paragraph

Destructive

Replace an exact code snippet in a paragraph with find-and-replace, automatically backing up previous content. Use for targeted edits instead of rewriting the whole paragraph.

Instructions

Replace an exact snippet of paragraph code (find-and-replace). Previous content is automatically backed up before changes.

Prefer this over update_paragraph for targeted changes — you send only the changed snippet
instead of the whole paragraph. Use update_paragraph for whole rewrites.

old_string must match the current code exactly, including whitespace and indentation: copy it
from get_paragraph_code (raw text), not from get_notebook/get_paragraph (they indent code by
2 spaces). Keep it minimal but unique — include a neighbouring line if the snippet repeats.

Args:
    notebook_id: The notebook ID containing the paragraph
    paragraph_id: The paragraph ID to edit
    old_string: Exact existing text to replace (must occur once unless replace_all)
    new_string: Replacement text
    replace_all: Replace every occurrence instead of requiring a unique match (e.g. renames)

Input Schema

Name	Required	Description	Default
`new_string`	Yes
`old_string`	Yes
`notebook_id`	Yes
`replace_all`	No
`paragraph_id`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.1Oct 26, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true, and the description adds the crucial mitigating context that previous content is automatically backed up before changes. It also discloses failure-relevant behavior: the match must occur exactly once unless replace_all is set, and replace_all is the escape hatch for renames.

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?

Front-loaded with purpose and the sibling routing rule, then matching constraints, then per-parameter notes. Every sentence adds information an agent would otherwise have to guess, and nothing is repeated from the schema beyond parameter names that are then given meaning.

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 five-parameter destructive mutation with 0% schema coverage, this covers everything needed to call it correctly: routing versus siblings, exact-match and uniqueness requirements, backup behavior, and replace_all semantics. Return values are covered by the output schema, so their absence from the description is not a 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?

Schema description coverage is 0%, so the description carries the full burden, and it documents all five parameters with real semantics — not just names. old_string and new_string get exact-match and uniqueness rules, replace_all gets a concrete use case (renames), and the two IDs are identified by role.

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?

States a specific verb and resource ('Replace an exact snippet of paragraph code') and immediately frames it as find-and-replace. It explicitly names the sibling update_paragraph and the boundary between them, so an agent can distinguish this from whole-paragraph rewrites without opening either 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?

Gives an explicit routing rule: prefer this over update_paragraph for targeted changes, use update_paragraph for whole rewrites. It also states the precondition for correct invocation (old_string must match exactly, copied from get_paragraph_code rather than get_notebook/get_paragraph because of 2-space indentation) and how to disambiguate repeated snippets.

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