Skip to content

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.

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.py
index 25c14f7e4d..af6a05efb9 100644
--- a/marimo/_ai/_tools/tools/cells.py
+++ b/marimo/_ai/_tools/tools/cells.py
@@ -6,7 +6,7 @@ from enum import Enum
from typing import TYPE_CHECKING, Optional
from marimo._ai._tools.base import ToolBase
-from marimo._ai._tools.types import SuccessResult
+from marimo._ai._tools.types import SuccessResult, ToolGuidelines
from marimo._ai._tools.utils.exceptions import ToolExecutionError
from marimo._ast.models import CellData
from 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_id
cell_id = args.cell_id
diff --git a/marimo/_ai/_tools/tools/datasource.py b/marimo/_ai/_tools/tools/datasource.py
index 48115d4365..4225af44fe 100644
--- a/marimo/_ai/_tools/tools/datasource.py
+++ b/marimo/_ai/_tools/tools/datasource.py
@@ -7,7 +7,7 @@ from typing import Optional
from marimo import _loggers
from marimo._ai._tools.base import ToolBase
-from marimo._ai._tools.types import SuccessResult
+from marimo._ai._tools.types import SuccessResult, ToolGuidelines
from marimo._ai._tools.utils.exceptions import ToolExecutionError
from marimo._data.models import DataTable
from 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_id
session = self.context.get_session(session_id)
diff --git a/marimo/_ai/_tools/tools/errors.py b/marimo/_ai/_tools/tools/errors.py
index 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, Optional
from marimo import _loggers
from marimo._ai._tools.base import ToolBase
from marimo._ai._tools.tools.cells import ErrorDetail
-from marimo._ai._tools.types import SuccessResult
+from marimo._ai._tools.types import SuccessResult, ToolGuidelines
from marimo._server.sessions import Session
from 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.py
index 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 ToolBase
from marimo._ai._tools.types import (
EmptyArgs,
SuccessResult,
+ ToolGuidelines,
)
from marimo._server.model import ConnectionState
from 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 args
context = self.context
diff --git a/marimo/_ai/_tools/tools/tables_and_variables.py b/marimo/_ai/_tools/tools/tables_and_variables.py
index 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, field
from typing import Optional
from marimo._ai._tools.base import ToolBase
-from marimo._ai._tools.types import SuccessResult
+from marimo._ai._tools.types import SuccessResult, ToolGuidelines
from marimo._data.models import DataTableColumn
from marimo._messaging.ops import VariableValue
from 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)