Get the notebook's current revision token: {"path", "rev"}.

rev is a short hash of the file's current on-disk content. Pass it as expected_rev to a mutating tool to guard against a concurrent external edit (e.g. the file being saved by an editor between your read and your write): if the file changed since this rev, the write is refused so you can re-read. Read-only. Mutating tools also return the new rev, so you can chain edits without re-reading.

Create a NEW empty .ipynb notebook at path (optionally with initial cells).

Use this instead of hand-writing notebook JSON. cells (optional) is a list of {cell_type, source, summary?} — the same shape as insert_cells — seeded in order; omit it for an empty notebook. Refuses to overwrite an existing file and requires the parent directory to exist (both error). The notebook is nbformat 4.5, so every created cell gets a stable id right away. Returns {"path", "num_cells", "ids"}. cell_type must be one of: code, markdown, raw.

List every cell as a compact outline (cheap overview).

Returns index, id, type, summary, num_lines, has_outputs, has_error per cell. id is the cell's stable identifier: unlike index it does NOT shift when cells are inserted/deleted/moved, so prefer addressing later edits by id. summary is the cell's leading # comment block (code) or leading lines (markdown/raw); has_error flags code cells whose outputs contain an error. Cell indices are 0-based. Call this first to orient before editing.

Read one or more cells at once, addressed by indices OR ids.

Pass exactly one of indices (0-based) or ids (stable cell.id from list_cells). Ids don't shift when cells move, so prefer them once listed. Prefer a single call with several targets over many single reads. Returns, per cell, its id and source plus (for code cells) execution_count, outputs_text (rendered stdout/results, with errors and [image/*] placeholders), has_error, and output_types. All targets are validated first: if any is invalid (bad index, unknown/duplicate id) the whole call errors. Never executes code; only reads stored outputs.

Large results are bounded: each cell's source is windowed (~8000 chars) and the response total is capped (~20000 chars). A windowed cell carries source_truncated/source_length/source_offset — page it by re-reading that target with a larger offset. Cells past the total budget come back as {index, id, type, source_length, content_omitted: true}; read them separately.

Insert a new cell BEFORE index (index == cell count appends).

cell_type must be one of: code, markdown, raw. Indices are 0-based. Optionally pass summary: a short description stored in cell metadata that becomes the cell's summary in list_cells (takes precedence over any leading # comment). Set it so later list_cells calls stay informative. Optionally pass expected_rev (from notebook_rev or a prior write) to refuse the write if the file changed on disk since then. Returns the new rev.

Insert several cells at once, contiguously BEFORE index (0-based).

Prefer this over many insert_cell calls when adding a block of cells: one round-trip, no index bookkeeping between inserts. cells is a list of objects {cell_type, source, summary?} inserted in order (index == cell count appends). The batch is atomic: all items are validated first, and if any is invalid nothing is written and the offending items are named — fix those and resend. Optionally pass expected_rev to guard against concurrent external edits. Returns {"indices": [...], "ids": [...], "rev": ...}.

Replace a cell's ENTIRE source. For small changes prefer patch_cell.

Target the cell by index (0-based) OR cell_id (stable id from list_cells); pass exactly one. Prefer cell_id after listing — it doesn't shift when other cells change, avoiding off-by-one edits to the wrong cell. Editing a code cell clears its outputs and execution_count (they are stale). Optionally pass summary to set the cell's metadata summary (omit to keep, "" to clear). Optionally pass expected_rev to refuse the write if the file changed on disk. Returns the new rev.

Preferred edit tool: replace a unique old substring with new in a cell.

Target the cell by index (0-based) OR cell_id (stable id from list_cells); pass exactly one. Prefer cell_id when chaining several patches — indices shift after inserts/deletes/moves, ids don't, so this avoids patching the wrong cell. old must occur exactly once in the cell; otherwise this errors and asks for more context. Keeps diffs small. Editing a code cell clears its outputs. Optionally pass expected_rev (from notebook_rev or a prior write) to refuse the write if the file changed on disk since. Returns the new rev, so chained patches can pass it forward without re-reading.

Delete a cell, addressed by index (0-based) OR cell_id (exactly one).

Prefer cell_id from list_cells — an id can't drift onto the wrong cell the way a stale index can. Optionally pass expected_rev to guard against concurrent external edits. Returns the new rev.

Move a cell to to_index (final position, 0-based).

Address the moved cell by from_index OR from_id (stable id; exactly one); the destination to_index is always positional. Does not clear outputs. Optionally pass expected_rev to guard against concurrent external edits. Returns the new rev.