The Jupyter MCP Server enables AI assistants to connect to and control Jupyter Notebooks in real-time through the Model Context Protocol, providing comprehensive notebook management, code execution, and multimodal output handling.
Core Capabilities:
File System Management: Browse files/directories with filtering, pagination, and depth control; search using glob patterns
Kernel Management: List available and running kernels with state, connection details, and specifications; monitor kernel resources and restart kernels as needed
Multi-Notebook Operations: Connect to existing or create new notebooks, switch between multiple notebooks seamlessly, list managed notebooks with status, restart kernels, and disconnect to release resources
Cell-Level Operations: Read cells with metadata and outputs (brief or detailed with pagination), insert new cells (code/markdown) at any position, delete cells individually or in batches, overwrite cell source with diff-style tracking, and execute cells with configurable timeouts and progress streaming
Direct Code Execution: Execute code in kernels without saving to notebooks, including Jupyter magic commands (%timeit, %pip install), shell commands (!git status), quick calculations, and debugging
Multimodal Support: Handle diverse output types including text, images, and plots; return image data in base64 format when ALLOW_IMG_OUTPUT is enabled
JupyterLab Integration: Access additional commands like run-all-cells and get-selected-cell when running in JupyterLab mode (enabled by default)
AI-Driven Features: Context-aware interactions understanding entire notebook context, smart execution with automatic adjustment based on cell output feedback, and the jupyter-cite prompt for citing specific cells
Flexible Deployment: Compatible with local Jupyter, JupyterHub, Google Colab, Datalayer hosted notebooks, and works with any MCP client (Claude Desktop, Cursor, Windsurf, etc.)
Provides interaction with Jupyter notebooks running in JupyterLab, allowing adding and executing code cells, creating markdown cells, and interacting with notebook content programmatically.
Offers functionality to download Earth data granules from NASA Earth Data, supporting parameters for folder name, dataset short name, count, temporal range, and bounding box.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Jupyter MCP Server insert a markdown cell at the top with the title 'Data Analysis Report'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server developed for AI to connect and manage Jupyter Notebooks in real-time — and scale your Code Sandbox from local to the cloud (Datalayer, Kaggle, Google Colab, Modal, Daytona, E2B, CoreWeave, Cloudflare...)
Developed by Datalayer - Join our Discord
📖 Documentation · 🔧 Tools · 💬 Community
No process to run. Datalayer now hosts this server for you at
https://mcp.datalayer.run/mcp — one endpoint for every agent and every notebook.
Sign in from your browser, approve what the agent may do, and your work keeps running
on the server after the agent disconnects.
One command to connect Claude Code, with /datalayer:notebook, /datalayer:run and
/datalayer:status on top:
/plugin marketplace add datalayer/jupyter-mcp-server
/plugin install datalayer→ Datalayer plugin for Claude Code
Free and open source, BSD 3-Clause — point it at any Jupyter you already run, local or JupyterHub, no account needed.
Built and maintained by Datalayer, where the same server drives always-on Notebooks with GPU Code Sandboxes and durable execution — so your agent keeps working on your data when your laptop does not.
No token to copy and paste. An agent that meets this server unauthenticated is told where to authenticate, opens your browser, and you sign in to Datalayer as yourself. The agent never sees your password — it receives a token scoped to what you approved, and you can disconnect one agent without touching the others.
What each agent may do is two separate decisions: the scopes you approve
(notebooks:read, notebooks:write, code:execute, data:read) say what kind of
operation it may perform, and your own Datalayer permissions still say which notebooks it
may touch. An agent can never reach a notebook you cannot.
Personal access tokens keep working, and remain the simpler path for a CLI or a script. → OAuth and identity
Pin code-sandboxes to match your jupyter-mcp-server. The sandbox variant
jupyter was renamed to jupyter-server in code-sandboxes 1.1.1, and the two packages
have to agree on the name.
Your | Install |
>= 1.5.0 |
|
< 1.5.0 |
|
# On 1.5.0 or later
pip install "jupyter-mcp-server>=1.5.0" "code-sandboxes>=1.1.1"
# Staying on an earlier jupyter-mcp-server
pip install "jupyter-mcp-server<1.5.0" "code-sandboxes<=1.0.9"An older server with a newer code-sandboxes installs cleanly and then fails on the
first execution with Unknown sandbox variant: jupyter.
→ Release notes
Jupyter MCP Server 2 runs on the MCP Python SDK 2
(mcp>=2,<3), the SDK's first major release. Nothing changes in how you start or
configure the server, in the tools, or for the MCP clients connecting to it — the protocol
is negotiated with each client as before. What changes is the Python environment:
Your |
|
>= 2.0.0 |
|
< 2.0.0 |
|
Both are pinned in the package, so pip sorts it out; an environment holding another
package that still pins mcp<2 has to stay on jupyter-mcp-server<2 until that package
moves. Writing an extension or a custom token verifier against the SDK? See the
release notes for the renamed
imports.
--provider is now --document-provider (env var PROVIDER → DOCUMENT_PROVIDER).
It only ever chose where the notebook documents live — jupyter for the collaboration
API of a Jupyter Server, datalayer for the Datalayer spacer — while the old name and its
help text suggested it also chose where code runs. Execution is picked separately, with
--sandbox-variant (jupyter-server, datalayer, daytona, e2b, coreweave,
cloudflare, kaggle, google-colab, monty, modal).
Nothing breaks in v1.3.2: --provider is still accepted as an alias, PROVIDER is still
read, and a /connect payload carrying "provider" is still understood. Move to the new
names when convenient — the old ones are deprecated, not removed.
Related MCP server: mcp-server-jupyter
⚡ Real-time control: Instantly view notebook changes as they happen.
🔁 Smart execution: Automatically adjusts when a cell run fails thanks to cell output feedback.
🧠 Context-aware: Understands the entire notebook context for more relevant interactions.
📊 Multimodal support: Support different output types, including images, plots, and text.
📚 Multi-notebook support: Seamlessly switch between multiple notebooks.
🎨 JupyterLab integration: Enhanced UI integration like automatic notebook opening.
🤝 MCP-compatible: Works with any MCP client, such as Claude Desktop, Cursor, Windsurf, and more.
🔍 Observability: Built-in hook system with OpenTelemetry integration for tracing tool calls and kernel executions.
Compatible with any Jupyter deployment (local, JupyterHub, ...) and with Datalayer hosted Notebooks, where the Code Sandboxes come with GPUs and the execution survives a disconnect.
Every tool, with its parameters, schema and return value, is generated from a live snapshot of the running server and published at jupyter-mcp-server.datalayer.tech/mcp — so it is never out of step with the code, which a table copied into this file would be.
They fall into four groups:
Server and code sandbox — browse the Jupyter file system, list kernels, connect to a server at runtime, and launch, select and terminate code sandboxes.
Notebooks — open, create and switch between notebooks, list them, read one, restart its kernel, release it.
Cells — read, insert, delete, move, reorder and edit cells, surgically or wholesale, and clear their outputs.
Execution — run a cell or arbitrary code on the active backend, with multimodal output and streaming where the sandbox supports it.
Sandbox tools need the optional jupyter_mcp_sandboxes extension; see
Sandbox Variants.
Available only when JupyterLab mode is enabled. It is enabled by default.
In JupyterLab mode the server also exposes JupyterLab commands as MCP tools through
jupyter-mcp-tools —
notebook_run-all-cells and notebook_get-selected-cell by default, with more
selectable through allowed_jupyter_mcp_tools. The full list and how to configure it are
in the Additional Tools documentation.
The server implements the MCP
prompts feature.
jupyter-cite cites specific cells from a notebook, the way @ does in a coding IDE or
CLI. Input parameters and returned content are in the
Prompts documentation.
For comprehensive setup instructions—including Streamable HTTP transport, running as a Jupyter Server extension and advanced configuration—check out our documentation. Or, get started quickly with JupyterLab and STDIO transport here below.
pip install jupyterlab jupyter-collaboration jupyter-mcp-tools ipykernelTo confirm your environment is correctly configured:
Open a notebook in JupyterLab
Type some content in any cell (code or markdown)
Observe the tab indicator: you should see an "×" appear next to the notebook name, indicating unsaved changes
Wait a few seconds—the "×" should automatically change to a "●" without manually saving
This automatic saving behavior confirms that the real-time collaboration features are working properly, which is essential for MCP server integration.
# Start JupyterLab on port 8888, allowing access from any IP and setting a token
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0If you are running notebooks through JupyterHub instead of JupyterLab as above, refer to our JupyterHub setup guide.
Next, configure your MCP client to connect to the server. We offer two primary methods—choose the one that best fits your needs:
📦 Using uvx (Recommended for Quick Start): A lightweight and fast method using uv. Ideal for local development and first-time users.
🐳 Using Docker (Recommended for Production): A containerized approach that ensures a consistent and isolated environment, perfect for production or complex setups.
First, install uv:
pip install uv
uv --version
# should be 0.6.14 or higherSee more details on uv installation.
Then, configure your client:
{
"mcpServers": {
"jupyter": {
"command": "uvx",
"args": ["jupyter-mcp-server@latest"],
"env": {
"JUPYTER_URL": "http://localhost:8888",
"JUPYTER_TOKEN": "MY_TOKEN",
"ALLOW_IMG_OUTPUT": "true"
}
}
}
}On macOS and Windows:
{
"mcpServers": {
"jupyter": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "JUPYTER_URL",
"-e", "JUPYTER_TOKEN",
"-e", "ALLOW_IMG_OUTPUT",
"datalayer/jupyter-mcp-server:latest"
],
"env": {
"JUPYTER_URL": "http://host.docker.internal:8888",
"JUPYTER_TOKEN": "MY_TOKEN",
"ALLOW_IMG_OUTPUT": "true"
}
}
}
}On Linux:
{
"mcpServers": {
"jupyter": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "JUPYTER_URL",
"-e", "JUPYTER_TOKEN",
"-e", "ALLOW_IMG_OUTPUT",
"--network=host",
"datalayer/jupyter-mcp-server:latest"
],
"env": {
"JUPYTER_URL": "http://localhost:8888",
"JUPYTER_TOKEN": "MY_TOKEN",
"ALLOW_IMG_OUTPUT": "true"
}
}
}
}Port Configuration: Ensure the port in your Jupyter URLs matches the one used in the jupyter lab command. For simplified config, set this in JUPYTER_URL.
Server Separation: Use JUPYTER_URL when both services are on the same server, or set individual variables for advanced deployments. The different URL variables exist because some deployments separate notebook storage (DOCUMENT_URL) from kernel execution (CODE_SANDBOX_URL).
Authentication: In most cases, document and code sandbox services use the same authentication token. Use JUPYTER_TOKEN for simplified config or set DOCUMENT_TOKEN and CODE_SANDBOX_TOKEN individually for different credentials.
Notebook Path: The DOCUMENT_ID parameter specifies the path to the notebook the MCP client default to connect. It should be relative to the directory where JupyterLab was started. If you omit DOCUMENT_ID, the MCP client can automatically list all available notebooks on the Jupyter server, allowing you to select one interactively via your prompts.
Image Output: Set ALLOW_IMG_OUTPUT to false if your LLM does not support mutimodel understanding.
For detailed instructions on configuring various MCP clients—including Claude Desktop, VS Code, Cursor, Cline, and Windsurf — see MCP Client Configuration.
By default, code executes through the code-sandboxes jupyter-server variant against
a Jupyter Server (SANDBOX_VARIANT=jupyter-server). Setting SANDBOX_VARIANT to any
other value uses another code-sandboxes
engine via the sandbox's plain kernel client when the selected variant exposes
one, so the same notebook tools can run code on additional backends.
The spelling is not fussy: google_colab, google-colab and GOOGLE-COLAB all name the
same variant. The names below are the canonical ones.
Sandbox features are provided by the optional jupyter_mcp_sandboxes extension.
To expose sandbox lifecycle tools (launch_sandbox, list_sandboxes,
use_sandbox, terminate_sandbox) or run any non-jupyter-server sandbox variant,
install it with pip install jupyter_mcp_sandboxes.
Engine |
| Extra install | Key variables | Docs |
Jupyter Server (default) |
| — |
| |
JupyterHub |
| — |
| |
Datalayer |
|
|
| |
Kaggle |
|
| Kaggle credentials, or | |
Google Colab |
|
|
| |
Monty |
|
| — | |
Modal |
|
| Modal credentials | |
Daytona |
|
|
| |
E2B |
|
|
| |
CoreWeave |
|
|
| |
Cloudflare |
|
|
|
Each engine has its own page with the credentials it needs, the accelerator options it accepts and a worked client configuration — start from jupyter-mcp-server.datalayer.tech/code-sandboxes.
Run the test suite:
pytest tests/Required environment variables for tests:
None for the default local suite.
Optional environment variables:
TEST_MCP_SERVER: true/false toggle for standalone MCP server mode tests (default true).
TEST_JUPYTER_SERVER: true/false toggle for Jupyter extension mode tests (default true).
DATALAYER_API_KEY: required only for Datalayer cloud smoke/integration tests.
DATALAYER_RUN_URL: optional custom Datalayer code sandbox URL for datalayer engine tests.
SANDBOX_ENVIRONMENT: optional cloud environment override (for example ai-agents-env).
Interact with LLMs that supports multimodal input (like Gemini 2.5 Pro) to fully utilize advanced multimodal understanding capabilities.
Use a MCP client that supports returning image data and can parse it (like Cursor, Gemini CLI, etc.), as some clients may not support this feature.
Break down complex task (like the whole data science workflow) into multiple sub-tasks (like data cleaning, feature engineering, model training, model evaluation, etc.) and execute them step-by-step.
Provide clearly structured prompts and rules (👉 Visit our Prompt Templates to get started)
Provide as much context as possible (like already installed packages, field explanations for existing datasets, current working directory, detailed task requirements, etc.).
We welcome contributions of all kinds! Here are some examples:
🐛 Bug fixes
📝 Improvements to existing features
🔧 New feature development
📚 Documentation improvements and prompt templates
For detailed instructions on how to get started with development and submit your contributions, please see our Contributing Guide.
Looking for blog posts, videos, or other materials about Jupyter MCP Server?
👉 Visit the Resources section in our documentation for more!
If this project is helpful to you, please give us a ⭐️
Made with ❤️ by Datalayer
Clear the outputs and execution count of a single code cell in the currently activated notebook, without deleting the cell itself.
| Name | Required | Description | Default |
|---|---|---|---|
| cell_index | Yes | Index of the code cell to clear (0-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message with the number of outputs removed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the destructiveHint annotation by clarifying that the cell itself is not deleted, only outputs are cleared. This resolves potential ambiguity about the tool's destructiveness. It does not mention permissions or side effects but sufficiently explains the behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded with the key action and context, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter, and there is an output schema present, so return values need not be detailed. The description covers the core functionality adequately. Missing edge cases like invalid indices are minor given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already describes the parameter well. The description does not add significant new meaning beyond confirming it operates on a single cell and reiterating the index's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'clear' and the specific resource 'outputs and execution count of a single code cell'. It also provides context (currently activated notebook) and distinguishes from deleting the cell, making it distinct from siblings like delete_cell.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives. While the context of siblings helps, the description itself lacks guidance on when to use or not use it, such as preferring it over delete_cell to retain the cell.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect to a Jupyter server dynamically with URL and token.
This tool allows you to connect to different Jupyter servers without needing to
restart the MCP server or modify configuration files. Particularly useful when:
- Working with multiple Jupyter servers with different ports/tokens
- Jupyter server token changes dynamically
- Need to switch between different Jupyter instances
Example usage:
- "Connect to http://localhost:8888 with token abc123"
- "Connect to http://localhost:8889 without authentication"
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | Provider type | jupyter |
| jupyter_url | Yes | Jupyter server URL to connect to (e.g., 'http://localhost:8888') | |
| jupyter_token | No | Jupyter server authentication token |
| Name | Required | Description |
|---|---|---|
| result | Yes | Connection status message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations set destructiveHint=true, but the description describes only connecting without any mention of destructive behavior or side effects, failing to add context about what gets destroyed or why the hint is set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: first sentence states purpose, second outlines use cases, third gives examples. It avoids fluff but could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage scenarios, and examples. With an output schema present, return values are not needed. However, it neglects to clarify the destructive hint, leaving a gap in behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema, like connecting without a token for no authentication, but does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool connects to a Jupyter server with URL and token, distinguishing it from sibling tools that operate on notebooks or files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists scenarios for use, such as multiple servers, dynamic tokens, and switching instances, with examples. It lacks explicit when-not-to-use but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete specific cells from the currently activated notebook and return the cell source of deleted cells (if include_source=True).
| Name | Required | Description | Default |
|---|---|---|---|
| cell_indices | Yes | List of cell indices to delete (0-based) | |
| include_source | No | Whether to include the source of deleted cells |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message with list of deleted cells and their source (if include_source=True) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true, which the description doesn't contradict. The description adds valuable behavioral context beyond annotations: it specifies what gets returned (cell source when include_source=True), clarifies the operation scope (currently activated notebook), and mentions the conditional return behavior. This provides useful operational details not covered by annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently communicates the core action, target, and key behavioral detail. Every element earns its place with no redundancy or unnecessary elaboration. It's front-loaded with the primary action and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has destructiveHint annotation, 100% schema coverage, and an output schema (implied by context signals), the description provides adequate context. It covers the main action, target resource, and key return behavior. However, it doesn't mention error conditions, what happens with invalid indices, or dependencies on notebook activation state, which could be helpful for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents both parameters. The description adds minimal semantic context by mentioning include_source parameter's effect on return values, but doesn't provide additional meaning beyond what the schema already states about cell_indices or include_source. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Delete specific cells'), identifies the target resource ('from the currently activated notebook'), and distinguishes from siblings by specifying it returns cell source (unlike other deletion or modification tools like overwrite_cell_source). It uses precise verb+resource+scope language.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('currently activated notebook') which suggests it should be used after activating a notebook via use_notebook, but doesn't explicitly state when to use this vs alternatives like overwrite_cell_source or when not to use it. No explicit alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform a surgical find-and-replace within a cell's source (like an editor's Edit tool).
Finds old_string in the cell and replaces it with new_string. Matching is literal
(not regex) and may span multiple lines. By default, old_string must appear exactly once;
set replace_all=True for multiple occurrences. Returns a diff of the changes made.
Prefer this over overwrite_cell_source for small, targeted edits — it is safer because
unchanged parts of the cell are left untouched. Use read_cell first to see the current
source and construct an accurate old_string.| Name | Required | Description | Default |
|---|---|---|---|
| cell_index | Yes | Index of the cell to edit (0-based) | |
| new_string | Yes | Replacement string | |
| old_string | Yes | Exact string to find in cell source | |
| replace_all | No | Replace all occurrences (default: first only) |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message with diff showing changes made |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: literal matching (not regex), multi-line support, default uniqueness of old_string, and replace_all option. Mentions return of a diff. Annotations include destructiveHint: true, which is consistent with description's 'safer' claim. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (4 sentences) and well-structured: first sentence states core purpose, second explains mechanics, third provides usage guidance and alternative, fourth suggests prerequisite action. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all essential aspects: purpose, mechanics, constraints, usage guidance, comparison with alternative, prerequisite, and return value (diff). Given 4 parameters, 3 required, and presence of output schema, the description is complete for agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds nuance: literal matching, multi-line, default uniqueness behavior for old_string, and semantics of replace_all (default first only). This adds meaningful context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool performs a surgical find-and-replace on a cell's source, using specific verb (edit) and resource (cell source). Explicitly distinguishes from sibling overwrite_cell_source by contrasting targeted edits vs full overwrite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use: prefer for small targeted edits over overwrite_cell_source. Recommends reading the cell first with read_cell to construct an accurate old_string. Provides clear usage conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a cell from the currently activated notebook with timeout and return it's outputs
| Name | Required | Description | Default |
|---|---|---|---|
| stream | No | Enable streaming progress (including time indicator) updates for long-running cells | |
| timeout | No | Maximum seconds to wait for execution (0 = use config default) | |
| cell_index | Yes | Index of the cell to execute (0-based) | |
| progress_interval | No | Seconds between progress updates when stream=True |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive hint, but the description adds minimal behavioral context beyond stating it returns outputs. It does not explain that execution modifies the notebook state (e.g., execution count, output storage), potential errors, or that streaming provides progress updates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence conveys the core purpose efficiently. Minor grammar issue ('it's' instead of 'its') but overall concise without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description does not detail the return value format (e.g., output type, error handling). It also omits the precondition of an activated notebook (only implied). For a destructive tool with rich parameters, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is documented. The description adds no extra meaning beyond the schema; it mentions 'with timeout' but the schema already describes the timeout parameter. Baseline 3 is appropriate as no incremental value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (execute a cell), resource (cell), and scope (from currently activated notebook). It differentiates from siblings like 'execute_code' by specifying it operates on an existing cell, but does not explicitly contrast with similar tools like 'insert_execute_code_cell'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., 'execute_code', 'insert_execute_code_cell'). The context of sibling tools implies a workflow, but the description does not provide any decision criteria or prerequisites beyond 'currently activated notebook'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute code directly in a kernel (not saved to notebook).
If `use_sandbox` selected an active sandbox, this tool executes on that
sandbox instead of a Jupyter kernel. This allows agents to switch between
kernel-backed and sandbox-backed execution using the same execute_code API.
Targets the current activated notebook's kernel by default. Pass kernel_id
to execute in a specific kernel directly — including raw kernels with no
notebook attached.
Recommended to use in following cases:
1. Execute Jupyter magic commands(e.g., `%timeit`, `%pip install xxx`)
2. Performance profiling and debugging.
3. View intermediate variable values(e.g., `print(xxx)`, `df.head()`)
4. Temporary calculations and quick tests(e.g., `np.mean(df['xxx'])`)
5. Execute Shell commands in Jupyter server(e.g., `!git xxx`)
Under no circumstances should you use this tool to:
1. Import new modules or perform variable assignments that affect subsequent Notebook execution
2. Execute dangerous code that may harm the Jupyter server or the user's data without permission
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Code to execute (supports magic commands with %, shell commands with !) | |
| timeout | No | Maximum seconds to wait for execution (0 = use config default) | |
| kernel_id | No | Target an existing kernel by ID (e.g. a raw kernel with no notebook). If omitted, uses the current notebook's kernel. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, which is reinforced by the warning about dangerous code. The description adds transparency about sandbox switching and non-persistence ('not saved to notebook'). However, it does not fully disclose all side effects (e.g., variable assignment persistence despite warning), but the warning covers key risks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, recommended uses, and forbidden uses. While somewhat lengthy, every section adds value. Minor redundancy in the bullet points, but overall efficient for the information density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers execution environment, constraints, and examples. It explains the dual execution modes and provides useful guidance. It does not describe return values, but the schema covers parameters well and the sibling tools list provides context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions. The description adds context beyond the schema by explaining kernel_id's use for raw kernels and the sandbox alternative. It helps agents understand parameter meaning but does not add extensive new details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The name 'execute_code' and initial sentence 'Execute code directly in a kernel (not saved to notebook)' clearly convey a specific verb and resource. This distinguishes it from sibling tools like 'execute_cell' (which executes notebook cells) and 'insert_execute_code_cell' (which inserts a new cell and executes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios (6 bullet points for recommended uses) and when-not-to-use (2 forbidden actions). It explains the sandbox vs kernel choice and the role of kernel_id, offering clear context for selecting this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a cell to specified position from the currently activated notebook.
| Name | Required | Description | Default |
|---|---|---|---|
| cell_type | Yes | Type of cell to insert | |
| cell_index | Yes | Target index for insertion (0-based), use -1 to append at end | |
| cell_source | Yes | Source content for the cell |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message and the structure of its surrounding cells |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, indicating mutation. The description adds minimal behavioral context by specifying 'currently activated notebook', implying a dependency on prior state, but doesn't detail effects like shifting other cells, permissions needed, or error handling. With annotations covering the destructive nature, a 3 is appropriate for limited added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Insert a cell') and includes essential context ('to specified position from the currently activated notebook'). There is no wasted verbiage, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (mutation with 3 parameters), high schema coverage (100%), presence of annotations (destructiveHint), and an output schema (implied by context signals), the description is reasonably complete. It could improve by addressing sibling differentiation or error cases, but it covers the basic operation adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear documentation for all parameters (e.g., cell_index with -1 for appending, cell_type enum). The description adds no parameter-specific semantics beyond what the schema provides, so it meets the baseline of 3 without compensating for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a cell') and the target ('currently activated notebook'), with the positional aspect ('to specified position') adding specificity. However, it doesn't explicitly differentiate from sibling tools like 'insert_execute_code_cell' or 'overwrite_cell_source', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'insert_execute_code_cell' for code execution or 'overwrite_cell_source' for modifying existing cells. It mentions the context ('currently activated notebook') but lacks explicit when/when-not instructions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a cell at specified index from the currently activated notebook and then execute it with timeout and return it's outputs It is a shortcut tool for insert_cell and execute_cell tools, recommended to use if you want to insert a cell and execute it at the same time
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | Maximum seconds to wait for execution (0 = use config default) | |
| cell_index | Yes | Index of the cell to insert and execute (0-based) | |
| cell_source | Yes | Code source for the cell |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint: true, so description does not need to add that. It does mention timeout and returning outputs, which adds some context beyond annotations. However, it does not disclose blocking behavior or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. All information is relevant and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 params, full schema coverage, no output schema, and sibling tools, the description adequately explains purpose, usage, and relationship to siblings. It does not define 'currently activated notebook' but that may be assumed from context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all three parameters with descriptions (100% coverage). The description adds 'with timeout' and 'specified index' but no new information beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Insert a cell and then execute it', identifies the resource (cell in activated notebook), and explicitly calls it a shortcut for insert_cell and execute_cell, distinguishing it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description recommends using this tool when you want to insert and execute simultaneously. It names alternative tools (insert_cell, execute_cell) but does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files and directories recursively in the Jupyter server's file system. Used to explore the file system structure of the Jupyter server or to find specific files or directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | The starting path to list from (empty string means root directory) | |
| limit | No | Maximum number of items to return (0 means no limit) | |
| pattern | No | Glob pattern to filter file paths | |
| max_depth | No | Maximum depth to recurse into subdirectories | |
| start_index | No | Starting index for pagination (0-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes | Tab-separated table with columns: Path, Type, Size, Last_Modified. Includes pagination info header. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. Description adds that listing is recursive and supports pattern filtering, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Efficiently conveys purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, no need to explain return values. Parameters fully described in schema. Description completes the picture for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3. Description does not add parameter-specific details beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List all files and directories recursively' and explains its use for exploring file system structure or finding specific files. It is distinct from sibling tools like list_notebooks and execute_cell.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives context for use: exploring file system or finding specific files. Does not explicitly state when not to use or compare to alternatives, but the sibling list_notebooks implies differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available kernels in the Jupyter server.
This tool shows all running and available kernel sessions on the Jupyter server, including their IDs, names, states, connection information, and kernel specifications. Useful for monitoring kernel resources and identifying specific kernels for connection.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes | Tab-separated table with columns: ID, Name, Display_Name, Language, State, Connections, Last_Activity, Environment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, but the description adds details on returned fields (IDs, names, states, etc.), which is helpful beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded main purpose, no filler. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description adequately explains the purpose and return content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. Baseline 3 applies since no additional param info is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all available kernels in the Jupyter server' with a specific verb and resource. It distinguishes from sibling tools like list_notebooks by focusing on kernels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Useful for monitoring kernel resources...' but does not explicitly mention when not to use or name alternatives like connect_to_jupyter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all notebooks that have been used via use_notebook tool
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes | TSV formatted table with notebook information |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, indicating a safe read operation, which the description doesn't contradict. The description adds context by specifying the scope ('notebooks that have been used via use_notebook tool'), which is useful behavioral information beyond annotations. However, it doesn't disclose other traits like rate limits, pagination, or return format, so it's adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the tool's purpose and scope without any wasted words. It's front-loaded with the main action and appropriately sized for a simple tool, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, read-only annotation, and an output schema exists), the description is reasonably complete. It specifies the scope of notebooks listed, which adds value beyond structured fields. However, it could slightly improve by hinting at the output format or usage context, but the presence of an output schema reduces this need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and 100% schema description coverage, the schema fully documents the lack of inputs. The description doesn't need to add parameter details, and it appropriately doesn't mention any, earning a high baseline score for not introducing confusion or redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all notebooks') and specifies a scope ('that have been used via use_notebook tool'), which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'list_files' or 'read_notebook', which could have overlapping functionality, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by referencing the 'use_notebook' tool, suggesting it's for notebooks that have been previously accessed. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'list_files' or 'read_notebook', nor does it specify exclusions or prerequisites, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a cell from source_index to target_index within the currently activated notebook.
The cell is removed from source_index and placed at target_index. Cells in between shift
to fill the gap. The cell's type, source, and outputs are preserved.
Example: in a notebook [A, B, C, D], move_cell(1, 3) produces [A, C, D, B].
Use this tool instead of manually deleting and re-inserting a cell — it is atomic and
preserves cell metadata. Use read_notebook first to see cell indices if needed.| Name | Required | Description | Default |
|---|---|---|---|
| source_index | Yes | Index of the cell to move (0-based) | |
| target_index | Yes | Destination index where the cell will end up (0-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message with moved cell info and surrounding context |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description details the removal, placement, and shifting of cells, and states that cell type, source, and outputs are preserved. It also notes atomicity. Annotations already include destructiveHint=true, and the description adds context beyond that without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear paragraphs: first explains the operation with an example, second provides usage guidance. Every sentence adds value, no redundancy, and the most important info is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With simple integer parameters, a clear schema, and an output schema, the description adequately explains the tool's behavior. It would benefit from mentioning error cases (e.g., out-of-bounds indices) but is complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description reinforces these by providing an example and explaining the shifting behavior. The example adds practical meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Move a cell from source_index to target_index within the currently activated notebook' with a specific verb-resource pair. Provides an example that clarifies the operation, and the name and description distinguish it from sibling tools like insert_cell, delete_cell, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool over manual delete and re-insert for atomicity and metadata preservation. Also suggests using read_notebook first to see indices. However, it does not explicitly mention when not to use it or compare with direct sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the entire source of a cell in the currently activated notebook. Returns a diff showing the changes made.
Use this when rewriting a cell completely. For small, targeted changes,
prefer edit_cell_source instead — it is safer for partial edits.| Name | Required | Description | Default |
|---|---|---|---|
| cell_index | Yes | Index of the cell to overwrite (0-based) | |
| cell_source | Yes | New complete cell source |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message with diff showing changes made |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true. The description adds that the tool returns a diff, which is behavioral insight. However, it does not elaborate on error conditions or permissions, but given annotation coverage, it is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences for main function plus a usage guideline sentence. No redundant information, front-loaded with purpose and immediate return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (2 required params) and presence of output schema (noting returns a diff), the description is fully adequate. It covers what, when, and return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add extra semantics beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Replace' with resource 'cell source' and mentions it works on the 'currently activated notebook'. It distinguishes from sibling 'edit_cell_source' by stating 'entire source' vs. partial edits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when rewriting a cell completely') and when not ('for small, targeted changes, prefer edit_cell_source'), providing a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a specific cell from the currently activated notebook and return it's metadata (index, type, execution count), source and outputs (for code cells)
| Name | Required | Description | Default |
|---|---|---|---|
| cell_index | Yes | Index of the cell to read (0-based) | |
| include_outputs | No | Include outputs in the response (only for code cells) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds that it reads from 'currently activated notebook' and returns metadata, source, and outputs. Does not mention behavior on invalid index or missing notebook, but acceptable for a non-destructive read with annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence covering purpose and return value. No filler or redundancy. Minor grammatical issue ('it's' should be 'its') but not affecting clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with 2 parameters and no output schema, the description adequately explains inputs and return fields. Missing mention of error conditions (e.g., out-of-range index) but sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for both parameters. Description does not add significant meaning beyond what schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Read a specific cell' and lists returned data (metadata, source, outputs). Unambiguously distinguishes from siblings like read_notebook (which reads entire notebook) and mutation tools (e.g., delete_cell, edit_cell_source).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Does not mention that it requires an activated notebook (use_notebook) or that include_outputs can be toggled to reduce response size. Lacks all usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a notebook and return index, source content, type, execution count of each cell.
Using brief format to get a quick overview of the notebook structure and it's useful for locating specific cells for operations like delete or insert. Using detailed format to get detailed information of the notebook and it's useful for debugging and analysis.
It is recommended to use brief format with larger limit to get a overview of the notebook structure, then use detailed format with exact index and limit to get the detailed information of some specific cells.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (0 means no limit) | |
| start_index | No | Starting index for pagination (0-based) | |
| notebook_name | Yes | Notebook identifier to read | |
| response_format | No | Response format: 'brief' will return first line and lines number, 'detailed' will return full cell source | brief |
| Name | Required | Description |
|---|---|---|
| result | Yes | Notebook content in the requested format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true. Description adds behavioral context: pagination via start_index and limit, response content differences between brief and detailed. No contradictions. Could mention if the tool is safe to call repeatedly, but overall good.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is three paragraphs, each serving a purpose: what it does, usage per format, and recommended workflow. Could be slightly tighter but no wasted sentences. Front-loaded with core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and output schema (not shown but exists), description covers all key aspects: pagination, format details, and best practices. Sufficient for agent to invoke correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description adds value by explaining that brief returns first line and line count, detailed returns full source, and gives usage advice for combining both. This augments the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reads a notebook and returns per-cell details (index, source, type, execution count). It distinguishes between brief and detailed formats. Siblings like list_notebooks or restart_notebook are distinct operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: brief for overview, detailed for debugging, and recommends using brief first then detailed for specific cells. This helps the agent choose the correct format and limit settings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart the kernel for a specific notebook.
| Name | Required | Description | Default |
|---|---|---|---|
| notebook_name | Yes | Notebook identifier to restart |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not add behavior beyond the destructiveHint annotation. Missing details like loss of in-memory variables, unsaved outputs, or impact on concurrent executions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence, but could be slightly improved by front-loading core information. However, it is not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for the action but lacks explanation of return value (output schema exists) or side effects beyond destructive hint. Adequate for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, and description adds minimal value by repeating 'Notebook identifier to restart'. Baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (restart) and resource (kernel for a specific notebook), distinguishing it from sibling tools like list_kernels or execute_cell.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as when a notebook is unresponsive or before executing new code. No mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unuse from a specific notebook and release its resources.
| Name | Required | Description | Default |
|---|---|---|---|
| notebook_name | Yes | Notebook identifier to disconnect |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation indicates destructiveHint=true, so the tool has destructive behavior. The description adds 'release its resources,' but does not detail what resources (e.g., kernel, memory) are affected or whether the action is reversible. More context is needed to fully inform the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. However, the phrasing 'Unuse from a specific notebook' is slightly awkward; 'Disconnect from a notebook' would be clearer. Still concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with one parameter, the description is somewhat complete. However, it does not mention the return value or side effects beyond releasing resources. With an output schema present, return values are covered there, but more behavioral context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the parameter has a description 'Notebook identifier to disconnect'), so the description does not need to add more. It simply restates that it's for a specific notebook, adding no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'unuse' from a notebook and release its resources. It distinguishes from sibling tools like connect_to_jupyter or restart_notebook by focusing on disconnecting and cleanup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not specify prerequisites, such as needing to be currently using the notebook, or when not to use it (e.g., if the notebook is needed later).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use a notebook and activate it for following cell operations. All cell operations will be performed on the currently activated notebook. Activate new notebook will deactivate the previously activated notebook. Reactivate previously activated notebook using same notebook_name and notebook_path.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Notebook operation mode: 'connect' to connect to existing and activate it, 'create' to create new and activate it | connect |
| kernel_id | No | Specific kernel ID to use (will create new if skipped) | |
| notebook_name | Yes | Unique identifier for the notebook | |
| notebook_path | Yes | Path to the notebook file, relative to the Jupyter server root (e.g. 'notebook.ipynb') |
| Name | Required | Description |
|---|---|---|
| result | Yes | Success message with notebook information |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the destructive behavior (deactivating previous notebook) which aligns with the destructiveHint annotation. It adds context about reactivation and activation effects beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three short sentences that immediately convey the core function and important behavioral notes. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description is nearly complete. It could mention a prerequisite like being connected to Jupyter, but that is implied by the sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented. The description adds minimal extra meaning beyond the schema, mentioning reactivation by name/path but not delving into syntax or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to activate a notebook for subsequent cell operations. It distinguishes from siblings like list_notebooks, unuse_notebook, and read_notebook by focusing on activation and state management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (before cell operations) and when to re-activate (use same name/path). It does not explicitly state alternatives or when not to use, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.7insert_execute_code_cellread_notebookuse_notebookv1.0.6clear_cell_outputexecute_code2 fields changedInput schema / properties / timeout / descriptionPrevious value: -"Execution timeout in seconds"New value: +"Maximum seconds to wait for execution (0 = use config default)"Input schema / properties / timeout / maximumRemoved value: -3600insert_execute_code_celllist_filesmove_celloverwrite_cell_sourcerestart_notebookunuse_notebookv1.0.5list_filesmove_celloverwrite_cell_sourceread_notebookrestart_notebookunuse_notebookuse_notebookv1.0.4connect_to_jupyteredit_cell_sourceexecute_cell3 fields changedInput schema / properties / timeout / defaultPrevious value: -90New value: +0Input schema / properties / timeout / descriptionPrevious value: -"Maximum seconds to wait for execution"New value: +"Maximum seconds to wait for execution (0 = use config default)"Output schema / (root)Previous value: -{
- "$defs": {
- "Annotations": {
- "additionalProperties": true,
- "properties": {
- "audience": {
- "anyOf": [
- {
- "items": {
- "enum": [
- "user",
- "assistant"
- ],
- "type": "string"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Audience"
- },
- "priority": {
- "anyOf": [
- {
- "maximum": 1,
- "minimum": 0,
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Priority"
- }
- },
- "title": "Annotations",
- "type": "object"
- },
- "ImageContent": {
- "additionalProperties": true,
- "description": "Image content for a message.",
- "properties": {
- "_meta": {
- "anyOf": [
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Meta"
- },
- "annotations": {
- "anyOf": [
- {
- "$ref": "#/$defs/Annotations"
- },
- {
- "type": "null"
- }
- ],
- "default": null
- },
- "data": {
- "title": "Data",
- "type": "string"
- },
- "mimeType": {
- "title": "Mimetype",
- "type": "string"
- },
- "type": {
- "const": "image",
- "title": "Type",
- "type": "string"
- }
- },
- "required": [
- "type",
- "data",
- "mimeType"
- ],
- "title": "ImageContent",
- "type": "object"
- }
- },
- "properties": {
- "result": {
- "description": "List of outputs from the executed cell",
- "items": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "$ref": "#/$defs/ImageContent"
- }
- ]
- },
- "title": "Result",
- "type": "array"
- }
- },
- "required": [
- "result"
- ],
- "title": "execute_cellOutput",
- "type": "object"
-}New value: +nullexecute_code3 fields changedInput schema / properties / kernel_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Target an existing kernel by ID (e.g. a raw kernel with no notebook). If omitted, uses the current notebook's kernel.",
+ "title": "Kernel Id"
+}Input schema / properties / timeout / maximumPrevious value: -60New value: +3600Output schema / (root)Previous value: -{
- "$defs": {
- "Annotations": {
- "additionalProperties": true,
- "properties": {
- "audience": {
- "anyOf": [
- {
- "items": {
- "enum": [
- "user",
- "assistant"
- ],
- "type": "string"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Audience"
- },
- "priority": {
- "anyOf": [
- {
- "maximum": 1,
- "minimum": 0,
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Priority"
- }
- },
- "title": "Annotations",
- "type": "object"
- },
- "ImageContent": {
- "additionalProperties": true,
- "description": "Image content for a message.",
- "properties": {
- "_meta": {
- "anyOf": [
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Meta"
- },
- "annotations": {
- "anyOf": [
- {
- "$ref": "#/$defs/Annotations"
- },
- {
- "type": "null"
- }
- ],
- "default": null
- },
- "data": {
- "title": "Data",
- "type": "string"
- },
- "mimeType": {
- "title": "Mimetype",
- "type": "string"
- },
- "type": {
- "const": "image",
- "title": "Type",
- "type": "string"
- }
- },
- "required": [
- "type",
- "data",
- "mimeType"
- ],
- "title": "ImageContent",
- "type": "object"
- }
- },
- "properties": {
- "result": {
- "description": "List of outputs from the executed code",
- "items": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "$ref": "#/$defs/ImageContent"
- }
- ]
- },
- "title": "Result",
- "type": "array"
- }
- },
- "required": [
- "result"
- ],
- "title": "execute_codeOutput",
- "type": "object"
-}New value: +nullinsert_execute_code_cell3 fields changedInput schema / properties / timeout / defaultPrevious value: -90New value: +0Input schema / properties / timeout / descriptionPrevious value: -"Maximum seconds to wait for execution"New value: +"Maximum seconds to wait for execution (0 = use config default)"Output schema / (root)Previous value: -{
- "$defs": {
- "Annotations": {
- "additionalProperties": true,
- "properties": {
- "audience": {
- "anyOf": [
- {
- "items": {
- "enum": [
- "user",
- "assistant"
- ],
- "type": "string"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Audience"
- },
- "priority": {
- "anyOf": [
- {
- "maximum": 1,
- "minimum": 0,
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Priority"
- }
- },
- "title": "Annotations",
- "type": "object"
- },
- "ImageContent": {
- "additionalProperties": true,
- "description": "Image content for a message.",
- "properties": {
- "_meta": {
- "anyOf": [
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Meta"
- },
- "annotations": {
- "anyOf": [
- {
- "$ref": "#/$defs/Annotations"
- },
- {
- "type": "null"
- }
- ],
- "default": null
- },
- "data": {
- "title": "Data",
- "type": "string"
- },
- "mimeType": {
- "title": "Mimetype",
- "type": "string"
- },
- "type": {
- "const": "image",
- "title": "Type",
- "type": "string"
- }
- },
- "required": [
- "type",
- "data",
- "mimeType"
- ],
- "title": "ImageContent",
- "type": "object"
- }
- },
- "properties": {
- "result": {
- "description": "List of outputs from the executed cell",
- "items": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "$ref": "#/$defs/ImageContent"
- }
- ]
- },
- "title": "Result",
- "type": "array"
- }
- },
- "required": [
- "result"
- ],
- "title": "insert_execute_code_cellOutput",
- "type": "object"
-}New value: +nullmove_cellread_cell1 field changedOutput schema / (root)Previous value: -{
- "$defs": {
- "Annotations": {
- "additionalProperties": true,
- "properties": {
- "audience": {
- "anyOf": [
- {
- "items": {
- "enum": [
- "user",
- "assistant"
- ],
- "type": "string"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Audience"
- },
- "priority": {
- "anyOf": [
- {
- "maximum": 1,
- "minimum": 0,
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Priority"
- }
- },
- "title": "Annotations",
- "type": "object"
- },
- "ImageContent": {
- "additionalProperties": true,
- "description": "Image content for a message.",
- "properties": {
- "_meta": {
- "anyOf": [
- {
- "additionalProperties": true,
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Meta"
- },
- "annotations": {
- "anyOf": [
- {
- "$ref": "#/$defs/Annotations"
- },
- {
- "type": "null"
- }
- ],
- "default": null
- },
- "data": {
- "title": "Data",
- "type": "string"
- },
- "mimeType": {
- "title": "Mimetype",
- "type": "string"
- },
- "type": {
- "const": "image",
- "title": "Type",
- "type": "string"
- }
- },
- "required": [
- "type",
- "data",
- "mimeType"
- ],
- "title": "ImageContent",
- "type": "object"
- }
- },
- "properties": {
- "result": {
- "description": "Cell information including index, type, source, and outputs (for code cells)",
- "items": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "$ref": "#/$defs/ImageContent"
- }
- ]
- },
- "title": "Result",
- "type": "array"
- }
- },
- "required": [
- "result"
- ],
- "title": "read_cellOutput",
- "type": "object"
-}New value: +nullv1.0.0delete_cellexecute_cellexecute_codeinsert_cellinsert_execute_code_celllist_fileslist_kernelslist_notebooksoverwrite_cell_sourceread_cellread_notebookrestart_notebookunuse_notebookuse_notebookMost tools have clearly distinct purposes (kernel management, code execution, cell manipulation). However, execute_cell and execute_code overlap in that both execute code; descriptions help distinguish but agents may still misselect. Some tools like list_files and list_notebooks are separate but related.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_kernels, execute_cell, insert_cell). The naming is predictable and intuitive, with no mixing of conventions.
With 15 tools, the server covers core notebook and kernel operations without being bloated. The number is appropriate for the domain, providing necessary functionality without excess.
The tool set covers many essential operations (connecting, listing files, executing code, managing cells), but lacks tools for creating new notebooks or listing all notebooks on the server. Users must rely on list_files to find notebooks, which is less direct.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Connect AI agents to Replynodes over the Model Context Protocol.
A Model Context Protocol server for Wix AI tools
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/datalayer/jupyter-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
