feat: create ToolGuidelines for better Agent orientation of when and how to use marimo tools, add guidelines to GetMarimoRules tool (#6793)

## 📝 Summary

<!--
Provide a concise summary of what this pull request is addressing.

If this PR fixes any issues, list them here by number (e.g., Fixes
#123).
-->

This improves tool guidance for agents by adding structured guidelines
that inform the agents not just what the tool is but when to and not to
use it ++:

<img width="954" height="290" alt="Screenshot 2025-10-15 at 3 55 22 PM"
src="https://github.com/user-attachments/assets/4a08e443-0736-41aa-9b5a-c5d1369b4b78"
/>

this also improves the Agent consistently using the GetMarimoRules tool:

<img width="332" height="538" alt="Screenshot 2025-10-15 at 4 23 28 PM"
src="https://github.com/user-attachments/assets/1127999a-dbfc-4805-a7d0-7d3742c6f49c"
/>


## 🔍 Description of Changes

<!--
Detail the specific changes made in this pull request. Explain the
problem addressed and how it was resolved. If applicable, provide before
and after comparisons, screenshots, or any relevant details to help
reviewers understand the changes easily.
-->
- Add `ToolGuidelines` to `types.py`
- Integrate `ToolGuidelines` into `base.py`
- Update `GetMarimoRules` class to improve usage

## 📋 Checklist

- [x] I have read the [contributor
guidelines](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md).
- [ ] For large changes, or changes that affect the public API: this
change was discussed or approved through an issue, on
[Discord](https://marimo.io/discord?ref=pr), or the community
[discussions](https://github.com/marimo-team/marimo/discussions) (Please
provide a link if applicable).
- [ ] I have added tests for the changes made.
- [x] I have run the code and verified that it works as expected.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: bjoaquinc

marimo/_ai/_tools/base.py

@@ -17,6 +17,7 @@
 )
 
 from marimo import _loggers
+from marimo._ai._tools.types import ToolGuidelines
 from marimo._ai._tools.utils.exceptions import ToolExecutionError
 from marimo._config.config import CopilotMode
 from marimo._server.ai.tools.types import (
@@ -95,6 +96,7 @@ class ToolBase(Generic[ArgsT, OutT], ABC):
     # Override in subclass, or rely on fallbacks below
     name: str = ""
     description: str = ""
+    guidelines: Optional[ToolGuidelines] = None
     Args: type[ArgsT]
     Output: type[OutT]
     context: ToolContext
@@ -127,7 +129,15 @@ def __init__(self, context: ToolContext) -> None:
 
         # get description from class docstring
         if self.description == "":
-            self.description = (self.__class__.__doc__ or "").strip()
+            base_description = (self.__class__.__doc__ or "").strip()
+
+            # If guidelines exist, append them
+            if self.guidelines is not None:
+                self.description = self._format_with_guidelines(
+                    base_description, self.guidelines
+                )
+            else:
+                self.description = base_description
 
     async def __call__(self, args: ArgsT) -> OutT:
         """
@@ -241,6 +251,34 @@ def _coerce_args(self, args: Any) -> ArgsT:  # type: ignore[override]
             return args  # type: ignore[return-value]
         return parse_raw(args, self.Args)
 
+    def _format_with_guidelines(
+        self, description: str, guidelines: ToolGuidelines
+    ) -> str:
+        """Combine description with structured guidelines."""
+        parts = [description] if description else []
+
+        if guidelines.when_to_use:
+            parts.append("\n## When to use:")
+            parts.extend(f"- {item}" for item in guidelines.when_to_use)
+
+        if guidelines.avoid_if:
+            parts.append("\n## Avoid if:")
+            parts.extend(f"- {item}" for item in guidelines.avoid_if)
+
+        if guidelines.prerequisites:
+            parts.append("\n## Prerequisites:")
+            parts.extend(f"- {item}" for item in guidelines.prerequisites)
+
+        if guidelines.side_effects:
+            parts.append("\n## Side effects:")
+            parts.extend(f"- {item}" for item in guidelines.side_effects)
+
+        if guidelines.additional_info:
+            parts.append("\n## Additional info:")
+            parts.append(guidelines.additional_info)
+
+        return "\n".join(parts)
+
     # error defaults/hooks
     def _default_error_code(self) -> str:
         return "UNEXPECTED_ERROR"

marimo/_ai/_tools/tools/rules.py

@@ -7,7 +7,7 @@
 import marimo._utils.requests as requests
 from marimo import _loggers
 from marimo._ai._tools.base import ToolBase
-from marimo._ai._tools.types import EmptyArgs, SuccessResult
+from marimo._ai._tools.types import EmptyArgs, SuccessResult, ToolGuidelines
 
 LOGGER = _loggers.marimo_logger()
 
@@ -29,6 +29,15 @@ class GetMarimoRules(ToolBase[EmptyArgs, GetMarimoRulesOutput]):
         The content of the rules file.
     """
 
+    guidelines = ToolGuidelines(
+        when_to_use=[
+            "Before using other marimo mcp tools, reading a marimo notebook, or writing to a notebook ALWAYS use this first to understand how marimo works",
+        ],
+        avoid_if=[
+            "The rules have already been retrieved recently, as they rarely change",
+        ],
+    )
+
     def handle(self, args: EmptyArgs) -> GetMarimoRulesOutput:
         del args
 

marimo/_ai/_tools/types.py

@@ -21,3 +21,14 @@ class SuccessResult:
 @dataclass
 class EmptyArgs:
     pass
+
+
+@dataclass
+class ToolGuidelines:
+    """Structured guidance for AI assistants on when and how to use a tool."""
+
+    when_to_use: Optional[list[str]] = None
+    avoid_if: Optional[list[str]] = None
+    prerequisites: Optional[list[str]] = None
+    side_effects: Optional[list[str]] = None
+    additional_info: Optional[str] = None