Skip to content

docs: warn about read_cell stale-output lag in jupyter-mcp guidance#16

Merged
KadenMc merged 1 commit into
mainfrom
docs/jupyter-mcp-read-cell-stale-warning
May 10, 2026
Merged

docs: warn about read_cell stale-output lag in jupyter-mcp guidance#16
KadenMc merged 1 commit into
mainfrom
docs/jupyter-mcp-read-cell-stale-warning

Conversation

@KadenMc
Copy link
Copy Markdown
Owner

@KadenMc KadenMc commented May 10, 2026

Summary

  • Adds a warning to the vendored AGENTS.md "Working with Jupyter MCP" section: read_cell / read_notebook outputs lag live kernel state after execute_cell. Cached output and execution count may still reflect the prior run.
  • Mitigation in the same bullet: trust execute_cell's return value to verify the most-recent execution, don't round-trip through read_cell.
  • Sits next to the existing notebook_run-all-cells 404 warning — both are "tool exists but has a footgun" notes in the same family.

Why

Discovered while smoke-testing the aexp install --with-jupyter integration end-to-end in a downstream consumer (electricrag). The agent's report:

read_cell — Works, but cached output lags live state — showed x = 1024 while execute_cell had just returned the new python 3.12 … output. The execution count was also stale by 1. Worth knowing: don't rely on read_cell outputs to verify the most-recent run; trust the execute_cell return value instead.

Without this note, a fresh agent that reaches for read_cell to confirm an execution will silently get stale data and act on it.

Scope

Documentation only. No tool/code changes. The underlying caching behavior is upstream (`jupyter-mcp-server`); a tighter fix would belong there but this warning gets agents unblocked immediately.

Test plan

  • Verify the new bullet renders well in the AGENTS.md flow (no list-formatting break)
  • Confirm the placement reads naturally next to the `notebook_run-all-cells` warning

🤖 Generated with Claude Code

read_cell / read_notebook return the notebook's cached output, which
lags live kernel state after execute_cell — execution counts and stdout
may still reflect the prior run. Surfaces a footgun an agent will
otherwise hit when using read_cell to "verify" an execution; the fix is
to trust execute_cell's return value instead.

Discovered while smoke-testing the aexp install --with-jupyter
integration in a downstream consumer (electricrag). Pairs naturally
with the existing notebook_run-all-cells warning — both are
"tool exists but has a footgun" notes in the same family.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@KadenMc KadenMc merged commit a7ed86d into main May 10, 2026
6 checks passed
@KadenMc KadenMc deleted the docs/jupyter-mcp-read-cell-stale-warning branch May 10, 2026 01:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant