A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
improvement: add tool guidelines to all backend/mcp tools (#6801)
Joaquin Corominad6bef64578ae
diff --git a/marimo/_ai/_tools/tools/cells.py b/marimo/_ai/_tools/tools/cells.pyindex 25c14f7e4d..af6a05efb9 100644--- a/marimo/_ai/_tools/tools/cells.py+++ b/marimo/_ai/_tools/tools/cells.py@@ -6,7 +6,7 @@ from enum import Enumfrom typing import TYPE_CHECKING, Optionalfrom marimo._ai._tools.base import ToolBase-from marimo._ai._tools.types import SuccessResult+from marimo._ai._tools.types import SuccessResult, ToolGuidelinesfrom marimo._ai._tools.utils.exceptions import ToolExecutionErrorfrom marimo._ast.models import CellDatafrom marimo._messaging.ops import VariableValue@@ -114,6 +114,16 @@ class GetLightweightCellMap(A success result containing lightweight cell previews and navigation info."""+ guidelines = ToolGuidelines(+ when_to_use=[+ "To get an overview of notebook structure and all cell IDs",+ "When navigating a notebook before making targeted changes",+ ],+ prerequisites=[+ "You must have a valid session id from an active notebook",+ ],+ )+def handle(self, args: GetLightweightCellMapArgs) -> GetLightweightCellMapOutput:@@ -209,6 +219,17 @@ class GetCellRuntimeData(A success result containing cell runtime data including code, errors, and variables."""+ guidelines = ToolGuidelines(+ when_to_use=[+ "When inspecting a specific cell's code, errors, or variables",+ "After identifying a cell of interest from the cell map",+ ],+ prerequisites=[+ "You must have a valid session id from an active notebook",+ "You must have a valid cell id from an active notebook",+ ],+ )+def handle(self, args: GetCellRuntimeDataArgs) -> GetCellRuntimeDataOutput:session_id = args.session_idcell_id = args.cell_iddiff --git a/marimo/_ai/_tools/tools/datasource.py b/marimo/_ai/_tools/tools/datasource.pyindex 48115d4365..4225af44fe 100644--- a/marimo/_ai/_tools/tools/datasource.py+++ b/marimo/_ai/_tools/tools/datasource.py@@ -7,7 +7,7 @@ from typing import Optionalfrom marimo import _loggersfrom marimo._ai._tools.base import ToolBase-from marimo._ai._tools.types import SuccessResult+from marimo._ai._tools.types import SuccessResult, ToolGuidelinesfrom marimo._ai._tools.utils.exceptions import ToolExecutionErrorfrom marimo._data.models import DataTablefrom marimo._server.sessions import Session@@ -51,6 +51,19 @@ class GetDatabaseTables(The tables returned contain information about the database, schema and connection name to use in forming SQL queries."""+ guidelines = ToolGuidelines(+ when_to_use=[+ "When exploring database tables from external connections (SQL databases)",+ "Before writing SQL queries to understand schema structure",+ ],+ prerequisites=[+ "You must have a valid session id from an active notebook",+ ],+ avoid_if=[+ "the user is asking about in-memory DataFrames, use the get_tables_and_variables tool instead",+ ],+ )+def handle(self, args: GetDatabaseTablesArgs) -> GetDatabaseTablesOutput:session_id = args.session_idsession = self.context.get_session(session_id)diff --git a/marimo/_ai/_tools/tools/errors.py b/marimo/_ai/_tools/tools/errors.pyindex 820537d75f..26f31d112f 100644--- a/marimo/_ai/_tools/tools/errors.py+++ b/marimo/_ai/_tools/tools/errors.py@@ -7,7 +7,7 @@ from typing import Any, Optionalfrom marimo import _loggersfrom marimo._ai._tools.base import ToolBasefrom marimo._ai._tools.tools.cells import ErrorDetail-from marimo._ai._tools.types import SuccessResult+from marimo._ai._tools.types import SuccessResult, ToolGuidelinesfrom marimo._server.sessions import Sessionfrom marimo._types.ids import CellId_t, SessionId@@ -45,6 +45,16 @@ class GetNotebookErrors(A success result containing per-cell error details and totals."""+ guidelines = ToolGuidelines(+ when_to_use=[+ "When the user reports errors or issues in their notebook",+ "Before debugging or fixing broken cells",+ ],+ prerequisites=[+ "You must have a valid session id from an active notebook",+ ],+ )+def handle(self, args: GetNotebookErrorsArgs) -> GetNotebookErrorsOutput:session = self.context.get_session(args.session_id)summaries = self._collect_errors(session)diff --git a/marimo/_ai/_tools/tools/notebooks.py b/marimo/_ai/_tools/tools/notebooks.pyindex 0d2d1b6553..ca9fe41eee 100644--- a/marimo/_ai/_tools/tools/notebooks.py+++ b/marimo/_ai/_tools/tools/notebooks.py@@ -8,6 +8,7 @@ from marimo._ai._tools.base import ToolBasefrom marimo._ai._tools.types import (EmptyArgs,SuccessResult,+ ToolGuidelines,)from marimo._server.model import ConnectionStatefrom marimo._server.models.home import MarimoFile@@ -60,6 +61,14 @@ class GetActiveNotebooks(ToolBase[EmptyArgs, GetActiveNotebooksOutput]):A success result containing summary statistics and notebook details."""+ guidelines = ToolGuidelines(+ when_to_use=[+ "At the start of marimo notebook interactions to get session IDs",+ "When receiving session-related errors",+ ],+ additional_info="Use the file paths returned by this tool to directly edit a notebook.",+ )+def handle(self, args: EmptyArgs) -> GetActiveNotebooksOutput:del argscontext = self.contextdiff --git a/marimo/_ai/_tools/tools/tables_and_variables.py b/marimo/_ai/_tools/tools/tables_and_variables.pyindex 1b31008e73..9f2023e24b 100644--- a/marimo/_ai/_tools/tools/tables_and_variables.py+++ b/marimo/_ai/_tools/tools/tables_and_variables.py@@ -5,7 +5,7 @@ from dataclasses import dataclass, fieldfrom typing import Optionalfrom marimo._ai._tools.base import ToolBase-from marimo._ai._tools.types import SuccessResult+from marimo._ai._tools.types import SuccessResult, ToolGuidelinesfrom marimo._data.models import DataTableColumnfrom marimo._messaging.ops import VariableValuefrom marimo._server.sessions import Session@@ -60,6 +60,19 @@ class GetTablesAndVariables(A success result containing tables (columns, primary keys, indexes, engine, etc.) and variables (value, data type)."""+ guidelines = ToolGuidelines(+ when_to_use=[+ "When inspecting in-memory DataFrames or Python variables in the notebook",+ "Before suggesting data operations to understand available data",+ ],+ prerequisites=[+ "You must have a valid session id from an active notebook",+ ],+ avoid_if=[+ "the user is asking about database tables or data sources, use the get_database_tables tool instead",+ ],+ )+def handle(self, args: TablesAndVariablesArgs) -> TablesAndVariablesOutput:session = self.context.get_session(args.session_id)return self._get_tables_and_variables(session, args.variable_names)