docs/guides/editor_features/tools.md
!!! warning "Experimental Feature" Tools are currently experimental and under active development. Tool definitions and availability may change.
marimo exposes a set of tools that allow AI assistants to interact with your notebooks. These tools enable AI agents to read notebook content, inspect cell runtime data, access variables, handle errors, and more.
Tool availability depends on which chat panel mode you use:
| Mode | Marimo notebook tools |
|---|---|
| Manual | — |
| Ask | Read-only inspection, data, debugging, and reference tools |
| Agent | All Ask tools plus editing tools |
| Code mode | Code execution tool and on-demand reference guides (see below) |
External AI applications can also access the Ask and Agent notebook tools through the marimo MCP server.
| Tool | Description |
|---|---|
| get_active_notebooks | List all currently active marimo notebooks. Returns summary statistics and notebook details including names, paths, and session IDs. Start here to discover which notebooks are available. |
| get_lightweight_cell_map | Get an overview of notebook structure showing a preview of each cell. Takes a session_id and optional preview_lines parameter. Returns cell IDs, preview text, line counts, cell types (code, markdown, SQL), runtime state (idle, running, queued, etc.), and has_output/has_console_output flags. |
| get_cell_runtime_data | Get detailed runtime information for one or more cells. Takes session_id and cell_ids (list) parameters. Returns full cell code, error details, runtime metadata (execution time, runtime state), and variables defined by each cell. |
| get_cell_outputs | Get execution output from one or more cells. Takes session_id and cell_ids (list) parameters. Returns visual output (HTML, charts, tables, etc.) with mimetype, stdout messages, and stderr messages for each cell. |
| get_cell_dependency_graph | Get the cell dependency graph showing variable ownership and cell relationships. Takes session_id and optional cell_id and depth parameters. Returns cell dependency info (defined variables with kind and runtime type, referenced variables, parent/child cells), a variable ownership map, multiply-defined variables, and cycle information. Use cell_id to center on a specific cell and depth to limit traversal hops. |
| Tool | Description |
|---|---|
| get_tables_and_variables | Get information about variables and data tables in a session. Takes session_id and variable_names parameters (empty list returns all). Returns table metadata (columns, primary keys, indexes, row counts) and variable values with data types. |
| get_database_tables | Get database schema information with optional query filtering. Takes session_id and optional query parameter (supports regex). Returns tables with connection name, database, schema, and table details. |
| Tool | Description |
|---|---|
| get_notebook_errors | Get all errors in the notebook organized by cell. Takes session_id parameter. Returns error summary (total errors, affected cells) and per-cell error details (type, message, traceback). |
| lint_notebook | Get all marimo lint errors in the notebook. Returns lint errors as defined in the lint rules documentation. |
| Tool | Description |
|---|---|
| get_marimo_rules | Get official marimo guidelines and best practices for AI assistants. Returns the content of the marimo rules file and source URL for understanding marimo-specific conventions. |
!!! note "Availability" These tools are only available when using the chat panel in agent mode. They are not exposed through the MCP server.
| Tool | Description |
|---|---|
| edit_notebook | Add, remove, or update cells in the notebook. Takes cell operations and modifications as parameters. Allows the AI agent to generate diffs that modify notebook structure and content. |
| run_stale_cells | Run cells that are stale (outdated due to upstream changes). Triggers execution of affected cells to update the notebook state. |
In any chat panel mode (Manual, Ask, Agent, or Code mode), marimo can give the assistant access to web search and URL fetching. These are provider-adaptive capabilities from Pydantic AI: marimo enables them automatically based on your installed packages and the model you are using.
marimo picks the best available option for each capability:
| Capability | Local fallback (installed in your environment) | Native (model provider supports it) |
|---|---|---|
| Web search | DuckDuckGo search when ddgs is installed | Provider-native web search (e.g. Anthropic, OpenAI Responses) |
| Web fetch | URL fetching via markdownify when installed | Provider-native web fetch |
| X search | — | xAI models with native X search support |
Local fallbacks take priority when their packages are installed. Otherwise, marimo uses the provider's native tools when your configured model supports them.
To enable web search and fetch on any model — including local models via Ollama — install the optional Pydantic AI extras:
pip install "pydantic-ai-slim[duckduckgo,web-fetch]"
When local packages are not installed, marimo enables native tools only if your model supports them. For example:
xai/grok-2-latest) can use native web search and X searchConfigure xAI in your marimo.toml or through the notebook settings — see the xAI provider guide.
!!! warning "Experimental" Code mode gives the assistant direct access to your notebook's kernel so it can make destructive changes to your notebook.
Code mode is available from the chat panel mode selector. Instead of the inspection and editing tools above, the assistant uses a different toolset oriented around running Python in the live kernel:
| Tool / capability | Description |
|---|---|
| execute_code | Run Python in the notebook kernel's scratchpad. The assistant uses this for all notebook mutations — adding cells, updating code, inspecting variables, and running logic. |
| gotchas | On-demand reference for name redefinition, cached module proxies, and other notebook traps. |
| notebook-improvements | On-demand reference for improving, optimizing, or cleaning up an existing notebook. |
| rich-representations | On-demand reference for custom widgets, visual encodings, and interactive output. |
Code mode loads the marimo pair skill as its system prompt, so the assistant follows the same conventions as external agent CLIs paired on your notebook.