docs: warn about read_cell stale-output lag in jupyter-mcp guidance#16
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
read_cell/read_notebookoutputs lag live kernel state afterexecute_cell. Cached output and execution count may still reflect the prior run.execute_cell's return value to verify the most-recent execution, don't round-trip throughread_cell.notebook_run-all-cells404 warning — both are "tool exists but has a footgun" notes in the same family.Why
Discovered while smoke-testing the
aexp install --with-jupyterintegration end-to-end in a downstream consumer (electricrag). The agent's report:Without this note, a fresh agent that reaches for
read_cellto 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
🤖 Generated with Claude Code