NotebookEditTool: Edit Notebook

Although .ipynb files are fundamentally JSON at their core, semantically they are not ordinary text files; instead, they are:

• A sequence of ordered cells
• A mix of code and markdown
• Accompanied by outputs, metadata, and language information

Directly modifying a Notebook as if it were plain text most commonly leads to two types of issues:

• The structure gets corrupted, making the file unreadable
• You intend to change just one cell but end up corrupting the entire notebook

This is why Claude Code handles it separately with the NotebookEditTool.

tools/NotebookEditTool/NotebookEditTool.ts:

export const inputSchema = z.strictObject({
  notebook_path: z.string(),
  cell_id: z.string().optional(),
  new_source: z.string(),
  cell_type: z.enum(['code', 'markdown']).optional(),
  edit_mode: z.enum(['replace', 'insert', 'delete']).optional(),
})

These fields indicate that its operational granularity is at the cell level, not on a whole-file string level.

It handles several things that standard file-editing tools do not:

• Requires the target file to be .ipynb
• Supports three types of cell operations: replace, insert, and delete
• Requires an explicit cell_type when inserting
• Validates whether the cell exists and whether its ID is valid
• Also enforces a "read-before-edit" approach, consistent with the standard file-editing workflow

The source code includes an important note:

// Require Read-before-Edit (matches FileEditTool/FileWriteTool).

This shows that Anthropic emphasizes consistency heavily:
Even when Notebooks are treated as special objects, the timing constraint of "take a read snapshot -> then edit" cannot be bypassed.

1. First, use Read to inspect the notebook's cell structure and content
2. Identify which cell needs modification
3. Use NotebookEditTool to perform a replace, insert, or delete operation
4. Return to the main thread to continue verifying the result

It might be technically feasible from a low-level format perspective, but it shouldn't be done from a product behavior standpoint.
Claude Code explicitly elevates Notebooks to their own dedicated document type.

No.
Its editing target is the cell, not the raw JSON block as a whole.

The value of NotebookEditTool lies in:

Claude Code didn't downlevel Notebooks to plain text, but instead created a separate, controlled editing pipeline specifically for this "code + documentation" hybrid format.