From c44a6be58f4a4447a9d057b3ca98331edb2297c5 Mon Sep 17 00:00:00 2001
From: MischaPanch <mischa.panch@gmail.com>
Date: Sat, 2 Aug 2025 17:38:20 +0200
Subject: [PATCH 1/7] Docs on connecting Serena to chatgpt

---
 docs/serena_on_chatgpt.md | 101 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 docs/serena_on_chatgpt.md

diff --git a/docs/serena_on_chatgpt.md b/docs/serena_on_chatgpt.md
new file mode 100644
index 00000000..64f7e248
--- /dev/null
+++ b/docs/serena_on_chatgpt.md
@@ -0,0 +1,101 @@
+
+# Connecting Serena MCP Server to ChatGPT via MCPO & Cloudflare Tunnel
+
+This guide explains how to expose a **locally running Serena MCP server** (powered by MCPO) to the internet using **Cloudflare Tunnel**, and how to connect it to **ChatGPT as a Custom GPT with tool access**.
+
+Once configured, ChatGPT becomes a powerful **coding agent** with direct access to your codebase, shell, and file system — so **read the security notes carefully**.
+
+---
+## Prerequisites
+
+Make sure you have [uv](https://docs.astral.sh/uv/getting-started/installation/) 
+and [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) installed.
+
+## 1. Start the Serena MCP Server via MCPO
+
+Run the following command to launch Serena as http server (assuming port 8000):
+
+```bash
+uvx mcpo --port 8000 --api-key <YOUR_SECRET_KEY> -- \
+  uvx --from git+https://github.com/oraios/serena \
+  serena start-mcp-server --project $(pwd)
+```
+
+- `--api-key` is required to secure the server.
+- `--project` should point to the root of your codebase.
+
+You can also use other options, and you don't have to pass `--project` if you want to work on multiple projects
+or want to activate it later. See 
+
+```shell
+uvx --from git+https://github.com/oraios/serena serena start-mcp-server --help
+```
+
+---
+
+## 2. Expose the Server Using Cloudflare Tunnel
+
+Run:
+
+```bash
+cloudflared tunnel --url http://localhost:8000
+```
+
+This will give you a **public HTTPS URL** like:
+
+```
+https://serena-agent-tunnel.trycloudflare.com
+```
+
+Your server is now securely exposed to the internet.
+
+---
+
+## 3. Connect It to ChatGPT (Custom GPT)
+
+### Steps:
+
+1. Go to [ChatGPT → Explore GPTs → Create](https://chat.openai.com/gpts/editor)
+2. During setup, click **“Add APIs”**
+3. Set up **API Key authentication** with the auth type as **Bearer** and enter the api key you used to start the MCPO server.
+4. In the **Schema** section, click on **import from URL** and paste `<cloudflared_url>/openapi.json` with the URL you got from the previous step.
+5. Add the following line to the top of the imported JSON schema:
+    ```
+     "servers": ["url": "<cloudflared_url>"],
+    ```
+
+ChatGPT will read the schema and create functions automatically.
+
+---
+
+## Security Warning — Read Carefully
+
+Depending on your configuration and enabled tools, Serena's MCP server may:
+- Execute **arbitrary shell commands**
+- Read, write, and modify **files in your codebase**
+
+This gives ChatGPT the same powers as a remote developer on your machine.
+
+### ⚠️ Key Rules:
+- **NEVER expose your API key**
+- **Only expose this server when needed**, and monitor its use.
+
+In your project’s `.serena/project.yml` or global config, you can disable tools like:
+
+```yaml
+excluded_tools:
+  - execute_shell_command
+  - ...
+read_only: true
+```
+
+This is strongly recommended if you want a read-only or safer agent.
+
+
+---
+
+## Final Thoughts
+
+With this setup, ChatGPT becomes a coding assistant **running on your local code** — able to index, search, edit, and even run shell commands depending on your configuration.
+
+Use responsibly, and keep security in mind.

From e41d09d9372d580e92835ca4980c00a432a9b03d Mon Sep 17 00:00:00 2001
From: MischaPanch <mischa.panch@gmail.com>
Date: Sat, 2 Aug 2025 18:55:34 +0200
Subject: [PATCH 2/7] Formatting

---
 src/solidlsp/language_servers/solargraph.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/solidlsp/language_servers/solargraph.py b/src/solidlsp/language_servers/solargraph.py
index 7b79c324..a4f7e694 100644
--- a/src/solidlsp/language_servers/solargraph.py
+++ b/src/solidlsp/language_servers/solargraph.py
@@ -7,7 +7,6 @@ import json
 import logging
 import os
 import pathlib
-import stat
 import subprocess
 import threading
 

From 46967fa3cbe5af325bcc9c07722ee9ee7d42aff9 Mon Sep 17 00:00:00 2001
From: MischaPanch <mischa.panch@gmail.com>
Date: Sat, 2 Aug 2025 18:56:09 +0200
Subject: [PATCH 3/7] Allow overriding tool descriptions in the context, cli
 command for tool description

---
 src/serena/agent.py                           | 10 ++++++++
 src/serena/cli.py                             | 24 ++++++++++++++++++-
 src/serena/config/context_mode.py             | 12 ++++++++--
 src/serena/mcp.py                             | 11 +++++++--
 .../resources/config/contexts/agent.yml       |  4 +++-
 .../config/contexts/context.template.yml      |  6 ++++-
 .../resources/config/contexts/desktop-app.yml |  3 ++-
 .../config/contexts/ide-assistant.yml         |  3 +++
 8 files changed, 65 insertions(+), 8 deletions(-)

diff --git a/src/serena/agent.py b/src/serena/agent.py
index 66394d62..7e900f34 100644
--- a/src/serena/agent.py
+++ b/src/serena/agent.py
@@ -227,6 +227,12 @@ class SerenaAgent:
             except Exception as e:
                 log.error(f"Error activating project '{project}' at startup: {e}", exc_info=e)
 
+    def get_context(self) -> SerenaAgentContext:
+        return self._context
+
+    def get_tool_description_override(self, tool_name: str) -> str | None:
+        return self._context.tool_description_overrides.get(tool_name, None)
+
     def _check_shell_settings(self) -> None:
         # On Windows, Claude Code sets COMSPEC to Git-Bash (often even with a path containing spaces),
         # which causes all sorts of trouble, preventing language servers from being launched correctly.
@@ -583,3 +589,7 @@ class SerenaAgent:
         if self._gui_log_viewer:
             log.info("Stopping the GUI log window ...")
             self._gui_log_viewer.stop()
+
+    def get_tool_by_name(self, tool_name: str) -> Tool:
+        tool_class = ToolRegistry().get_tool_class_by_name(tool_name)
+        return self.get_tool(tool_class)
diff --git a/src/serena/cli.py b/src/serena/cli.py
index 6b46a8e8..457b3acb 100644
--- a/src/serena/cli.py
+++ b/src/serena/cli.py
@@ -26,7 +26,7 @@ from serena.constants import (
     USER_CONTEXT_YAMLS_DIR,
     USER_MODE_YAMLS_DIR,
 )
-from serena.mcp import SerenaMCPFactorySingleProcess
+from serena.mcp import SerenaMCPFactory, SerenaMCPFactorySingleProcess
 from serena.project import Project
 from serena.tools import ToolRegistry
 from serena.util.logging import MemoryLogHandler
@@ -478,6 +478,28 @@ class ToolCommands(AutoRegisteringGroup):
         else:
             ToolRegistry().print_tool_overview()
 
+    @staticmethod
+    @click.command(
+        "description",
+        help="Print the description of a tool, optionally with a specific context (the latter may modify the default description).",
+    )
+    @click.argument("tool_name", type=str)
+    @click.option("--context", type=str, default=None, help="Context name or path to context file.")
+    def description(tool_name: str, context: str | None = None) -> None:
+        # Load the context
+        serena_context = None
+        if context:
+            serena_context = SerenaAgentContext.load(context)
+
+        agent = SerenaAgent(
+            project=None,
+            serena_config=SerenaConfig(web_dashboard=False, log_level=logging.INFO),
+            context=serena_context,
+        )
+        tool = agent.get_tool_by_name(tool_name)
+        mcp_tool = SerenaMCPFactory.make_mcp_tool(tool)
+        click.echo(mcp_tool.description)
+
 
 class PromptCommands(AutoRegisteringGroup):
     def __init__(self) -> None:
diff --git a/src/serena/config/context_mode.py b/src/serena/config/context_mode.py
index de84f6a7..30caba0b 100644
--- a/src/serena/config/context_mode.py
+++ b/src/serena/config/context_mode.py
@@ -4,7 +4,7 @@ Context and Mode configuration loader
 
 import os
 from copy import copy
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, field
 from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING, Self
@@ -134,6 +134,8 @@ class SerenaAgentContext(ToolInclusionDefinition, ToStringMixin):
     name: str
     prompt: str
     description: str = ""
+    tool_description_overrides: dict[str, str] = field(default_factory=dict)
+    """Maps tool names to custom descriptions, default descriptions are extracted from the tool docstrings."""
 
     def _tostring_includes(self) -> list[str]:
         return ["name"]
@@ -147,6 +149,9 @@ class SerenaAgentContext(ToolInclusionDefinition, ToStringMixin):
     def from_json_dict(cls, data: dict) -> Self:
         data = copy(data)
         data["excluded_tools"] = set(data["excluded_tools"])
+        # Ensure backwards compatibility for tool_description_overrides
+        if "tool_description_overrides" not in data:
+            data["tool_description_overrides"] = {}
         return cls(**data)
 
     @classmethod
@@ -155,7 +160,10 @@ class SerenaAgentContext(ToolInclusionDefinition, ToStringMixin):
         with open(yaml_path, encoding="utf-8") as f:
             data = yaml.safe_load(f)
         name = data.pop("name", Path(yaml_path).stem)
-        return cls(name=name, **data)
+        prompt = data["prompt"]
+        description = data.get("description", "")
+        tool_description_overrides = data.get("tool_description_overrides", {})
+        return cls(name=name, prompt=prompt, description=description, tool_description_overrides=tool_description_overrides)
 
     @classmethod
     def get_path(cls, name: str) -> str:
diff --git a/src/serena/mcp.py b/src/serena/mcp.py
index 9926af8e..6c75556f 100644
--- a/src/serena/mcp.py
+++ b/src/serena/mcp.py
@@ -68,10 +68,16 @@ class SerenaMCPFactory:
 
         # Mount the tool description as a combination of the docstring description and
         # the return value description, if it exists.
-        if docstring.description:
-            func_doc = f"{docstring.description.strip().strip('.')}."
+        agent = cast(SerenaAgent, tool.agent)
+        overridden_description = agent.get_context().tool_description_overrides.get(func_name, None)
+
+        if overridden_description is not None:
+            func_doc = overridden_description
+        elif docstring.description:
+            func_doc = docstring.description
         else:
             func_doc = ""
+        func_doc = func_doc.strip().strip(".")
         if docstring.returns and (docstring_returns_descr := docstring.returns.description):
             # Only add a space before "Returns" if func_doc is not empty
             prefix = " " if func_doc else ""
@@ -113,6 +119,7 @@ class SerenaMCPFactory:
             for tool in self._iter_tools():
                 mcp_tool = self.make_mcp_tool(tool)
                 mcp._tool_manager._tools[tool.get_name()] = mcp_tool
+            log.info(f"Starting MCP server with {len(mcp._tool_manager._tools)} tools: {list(mcp._tool_manager._tools.keys())}")
 
     @abstractmethod
     def _instantiate_agent(self, serena_config: SerenaConfig, modes: list[SerenaAgentMode]) -> None:
diff --git a/src/serena/resources/config/contexts/agent.yml b/src/serena/resources/config/contexts/agent.yml
index d3da9da9..e2984283 100644
--- a/src/serena/resources/config/contexts/agent.yml
+++ b/src/serena/resources/config/contexts/agent.yml
@@ -3,4 +3,6 @@ prompt: |
   You are running in agent context where the system prompt is provided externally. You should use symbolic
   tools when possible for code understanding and modification.
 excluded_tools:
-  - initial_instructions
\ No newline at end of file
+  - initial_instructions
+
+tool_description_overrides: {}
\ No newline at end of file
diff --git a/src/serena/resources/config/contexts/context.template.yml b/src/serena/resources/config/contexts/context.template.yml
index 52e94535..f9dee588 100644
--- a/src/serena/resources/config/contexts/context.template.yml
+++ b/src/serena/resources/config/contexts/context.template.yml
@@ -1,4 +1,8 @@
 # See Serena's documentation for more details on concept of contexts.
 description: Description of the context, not used in the code.
 prompt: Prompt that will form part of the system prompt/initial instructions for agents started in this context.
-excluded_tools: []
\ No newline at end of file
+excluded_tools: []
+
+# mapping of tool names to an override of their descriptions (the default description is the docstring of the Tool's apply method).
+# Sometimes, tool descriptions are too long (e.g., for ChatGPT), or users may want to override them for another reason.
+tool_description_overrides: {}
\ No newline at end of file
diff --git a/src/serena/resources/config/contexts/desktop-app.yml b/src/serena/resources/config/contexts/desktop-app.yml
index ea1567fb..8105ca8d 100644
--- a/src/serena/resources/config/contexts/desktop-app.yml
+++ b/src/serena/resources/config/contexts/desktop-app.yml
@@ -10,4 +10,5 @@ prompt: |
   If complex relationships that the user asked for should be visualized or explained, consider creating
   a diagram in addition to your text-based communication. Note that in the chat interface you have various rendering
   options for text, html, and mermaid diagrams, as has been explained to you in your initial instructions.
-excluded_tools: []
\ No newline at end of file
+excluded_tools: []
+tool_description_overrides: {}
diff --git a/src/serena/resources/config/contexts/ide-assistant.yml b/src/serena/resources/config/contexts/ide-assistant.yml
index 2a6c9e2c..14d65130 100644
--- a/src/serena/resources/config/contexts/ide-assistant.yml
+++ b/src/serena/resources/config/contexts/ide-assistant.yml
@@ -26,3 +26,6 @@ excluded_tools:
   - prepare_for_new_conversation
   - summarize_changes
   - get_current_config
+
+tool_description_overrides: {}
+

From eb0f44cb793e2fb34603d53fb471396ca40e74f5 Mon Sep 17 00:00:00 2001
From: MischaPanch <mischa.panch@gmail.com>
Date: Sat, 2 Aug 2025 20:03:19 +0200
Subject: [PATCH 4/7] Fixed appending of "." to docstring and mock in test...

We should get rid of mocks eventually
---
 src/serena/mcp.py       |  5 +++--
 test/serena/test_mcp.py | 23 ++++++++++++++---------
 2 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/src/serena/mcp.py b/src/serena/mcp.py
index 6c75556f..fb42cbe9 100644
--- a/src/serena/mcp.py
+++ b/src/serena/mcp.py
@@ -68,8 +68,7 @@ class SerenaMCPFactory:
 
         # Mount the tool description as a combination of the docstring description and
         # the return value description, if it exists.
-        agent = cast(SerenaAgent, tool.agent)
-        overridden_description = agent.get_context().tool_description_overrides.get(func_name, None)
+        overridden_description = tool.agent.get_context().tool_description_overrides.get(func_name, None)
 
         if overridden_description is not None:
             func_doc = overridden_description
@@ -78,6 +77,8 @@ class SerenaMCPFactory:
         else:
             func_doc = ""
         func_doc = func_doc.strip().strip(".")
+        if func_doc:
+            func_doc += "."
         if docstring.returns and (docstring_returns_descr := docstring.returns.description):
             # Only add a space before "Returns" if func_doc is not empty
             prefix = " " if func_doc else ""
diff --git a/test/serena/test_mcp.py b/test/serena/test_mcp.py
index 37b6eca8..731a1cc6 100644
--- a/test/serena/test_mcp.py
+++ b/test/serena/test_mcp.py
@@ -4,16 +4,28 @@ import pytest
 from mcp.server.fastmcp.tools.base import Tool as MCPTool
 
 from serena.agent import Tool, ToolRegistry
+from serena.config.context_mode import SerenaAgentContext
 from serena.mcp import SerenaMCPFactory
 
 make_tool = SerenaMCPFactory.make_mcp_tool
 
 
+# Create a mock agent for tool initialization
+class MockAgent:
+    def __init__(self):
+        self.project_config = None
+        self.serena_config = None
+
+    @staticmethod
+    def get_context() -> SerenaAgentContext:
+        return SerenaAgentContext.load_default()
+
+
 class BaseMockTool(Tool):
     """A mock Tool class for testing."""
 
-    def __init__(self) -> None:
-        pass
+    def __init__(self):
+        super().__init__(MockAgent())
 
 
 class BasicTool(BaseMockTool):
@@ -274,13 +286,6 @@ def is_test_mock_class(tool_class: type) -> bool:
 @pytest.mark.parametrize("tool_class", ToolRegistry().get_all_tool_classes())
 def test_make_tool_all_tools(tool_class) -> None:
     """Test that make_tool works for all tools in the codebase."""
-
-    # Create a mock agent for tool initialization
-    class MockAgent:
-        def __init__(self):
-            self.project_config = None
-            self.serena_config = None
-
     # Create an instance of the tool
     tool_instance = tool_class(MockAgent())
 

From 4410f37ab3b26f97a11903b1faa0e99f01c93742 Mon Sep 17 00:00:00 2001
From: MischaPanch <mischa.panch@gmail.com>
Date: Sat, 2 Aug 2025 22:49:42 +0200
Subject: [PATCH 5/7] Context: back to using **data in from_yaml, remove
 to/from json_dict methods

Needed since some fields come from parent class, easy to make mistakes (like I did in the past commit)
---
 src/serena/config/context_mode.py | 33 ++++---------------------------
 1 file changed, 4 insertions(+), 29 deletions(-)

diff --git a/src/serena/config/context_mode.py b/src/serena/config/context_mode.py
index 30caba0b..e04f3383 100644
--- a/src/serena/config/context_mode.py
+++ b/src/serena/config/context_mode.py
@@ -44,17 +44,6 @@ class SerenaAgentMode(ToolInclusionDefinition, ToStringMixin):
     def _tostring_includes(self) -> list[str]:
         return ["name"]
 
-    def to_json_dict(self) -> dict[str, str | list[str]]:
-        result = asdict(self)
-        result["excluded_tools"] = list(result["excluded_tools"])
-        return result
-
-    @classmethod
-    def from_json_dict(cls, data: dict) -> Self:
-        data = copy(data)
-        data["excluded_tools"] = set(data["excluded_tools"])
-        return cls(**data)
-
     def print_overview(self) -> None:
         """Print an overview of the mode."""
         print(f"{self.name}:\n {self.description}")
@@ -140,30 +129,16 @@ class SerenaAgentContext(ToolInclusionDefinition, ToStringMixin):
     def _tostring_includes(self) -> list[str]:
         return ["name"]
 
-    def to_json_dict(self) -> dict[str, str | list[str]]:
-        result = asdict(self)
-        result["excluded_tools"] = list(result["excluded_tools"])
-        return result
-
-    @classmethod
-    def from_json_dict(cls, data: dict) -> Self:
-        data = copy(data)
-        data["excluded_tools"] = set(data["excluded_tools"])
-        # Ensure backwards compatibility for tool_description_overrides
-        if "tool_description_overrides" not in data:
-            data["tool_description_overrides"] = {}
-        return cls(**data)
-
     @classmethod
     def from_yaml(cls, yaml_path: str | Path) -> Self:
         """Load a context from a YAML file."""
         with open(yaml_path, encoding="utf-8") as f:
             data = yaml.safe_load(f)
         name = data.pop("name", Path(yaml_path).stem)
-        prompt = data["prompt"]
-        description = data.get("description", "")
-        tool_description_overrides = data.get("tool_description_overrides", {})
-        return cls(name=name, prompt=prompt, description=description, tool_description_overrides=tool_description_overrides)
+        # Ensure backwards compatibility for tool_description_overrides
+        if "tool_description_overrides" not in data:
+            data["tool_description_overrides"] = {}
+        return cls(name=name, **data)
 
     @classmethod
     def get_path(cls, name: str) -> str:

From 99757f35ebd53173c397379d4884c70cacc3981e Mon Sep 17 00:00:00 2001
From: MischaPanch <mischa.panch@gmail.com>
Date: Sun, 3 Aug 2025 00:14:11 +0200
Subject: [PATCH 6/7] Made more tools optional and shortened several docstrings

---
 docs/serena_on_chatgpt.md                     |  3 +-
 scripts/demo_run_tools.py                     | 10 ++---
 src/serena/config/context_mode.py             |  3 +-
 .../config/contexts/context.template.yml      |  3 ++
 .../resources/config/contexts/desktop-app.yml |  3 ++
 .../config/contexts/ide-assistant.yml         |  5 ---
 .../resources/config/modes/mode.template.yml  |  3 ++
 src/serena/tools/cmd_tools.py                 | 11 +----
 src/serena/tools/config_tools.py              |  8 ++--
 src/serena/tools/file_tools.py                | 20 +++------
 src/serena/tools/memory_tools.py              | 11 +----
 src/serena/tools/symbol_tools.py              | 44 +++++++++----------
 src/serena/tools/workflow_tools.py            |  2 +-
 13 files changed, 52 insertions(+), 74 deletions(-)

diff --git a/docs/serena_on_chatgpt.md b/docs/serena_on_chatgpt.md
index 64f7e248..ec872696 100644
--- a/docs/serena_on_chatgpt.md
+++ b/docs/serena_on_chatgpt.md
@@ -18,7 +18,7 @@ Run the following command to launch Serena as http server (assuming port 8000):
 ```bash
 uvx mcpo --port 8000 --api-key <YOUR_SECRET_KEY> -- \
   uvx --from git+https://github.com/oraios/serena \
-  serena start-mcp-server --project $(pwd)
+  serena start-mcp-server --context chatgpt --project $(pwd)
 ```
 
 - `--api-key` is required to secure the server.
@@ -63,6 +63,7 @@ Your server is now securely exposed to the internet.
     ```
      "servers": ["url": "<cloudflared_url>"],
     ```
+   **Important**: don't include a trailing slash at the end of the URL!
 
 ChatGPT will read the schema and create functions automatically.
 
diff --git a/scripts/demo_run_tools.py b/scripts/demo_run_tools.py
index 394fe553..d52cfb00 100644
--- a/scripts/demo_run_tools.py
+++ b/scripts/demo_run_tools.py
@@ -9,7 +9,7 @@ from pprint import pprint
 from serena.agent import SerenaAgent
 from serena.config.serena_config import SerenaConfig
 from serena.constants import REPO_ROOT
-from serena.tools import FindFileTool, FindReferencingSymbolsTool, SearchForPatternTool
+from serena.tools import FindFileTool, FindReferencingSymbolsTool, GetSymbolsOverviewTool, SearchForPatternTool
 
 if __name__ == "__main__":
     agent = SerenaAgent(project=REPO_ROOT, serena_config=SerenaConfig(gui_log_window_enabled=False, web_dashboard=False))
@@ -18,13 +18,9 @@ if __name__ == "__main__":
     find_refs_tool = agent.get_tool(FindReferencingSymbolsTool)
     find_file_tool = agent.get_tool(FindFileTool)
     search_pattern_tool = agent.get_tool(SearchForPatternTool)
+    overview_tool = agent.get_tool(GetSymbolsOverviewTool)
 
     result = agent.execute_task(
-        lambda: search_pattern_tool.apply(
-            r"def request_full_.*?\).*?\)",
-            restrict_search_to_code_files=False,
-            relative_path="src/solidlsp",
-            paths_include_glob="**/ls.py",
-        )
+        lambda: overview_tool.apply("src/solidlsp/ls.py"),
     )
     pprint(json.loads(result))
diff --git a/src/serena/config/context_mode.py b/src/serena/config/context_mode.py
index e04f3383..fbe34091 100644
--- a/src/serena/config/context_mode.py
+++ b/src/serena/config/context_mode.py
@@ -3,8 +3,7 @@ Context and Mode configuration loader
 """
 
 import os
-from copy import copy
-from dataclasses import asdict, dataclass, field
+from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING, Self
diff --git a/src/serena/resources/config/contexts/context.template.yml b/src/serena/resources/config/contexts/context.template.yml
index f9dee588..c01a1177 100644
--- a/src/serena/resources/config/contexts/context.template.yml
+++ b/src/serena/resources/config/contexts/context.template.yml
@@ -3,6 +3,9 @@ description: Description of the context, not used in the code.
 prompt: Prompt that will form part of the system prompt/initial instructions for agents started in this context.
 excluded_tools: []
 
+# several tools are excluded by default and have to be explicitly included by the user
+included_optional_tools: []
+
 # mapping of tool names to an override of their descriptions (the default description is the docstring of the Tool's apply method).
 # Sometimes, tool descriptions are too long (e.g., for ChatGPT), or users may want to override them for another reason.
 tool_description_overrides: {}
\ No newline at end of file
diff --git a/src/serena/resources/config/contexts/desktop-app.yml b/src/serena/resources/config/contexts/desktop-app.yml
index 8105ca8d..c3adcfb4 100644
--- a/src/serena/resources/config/contexts/desktop-app.yml
+++ b/src/serena/resources/config/contexts/desktop-app.yml
@@ -11,4 +11,7 @@ prompt: |
   a diagram in addition to your text-based communication. Note that in the chat interface you have various rendering
   options for text, html, and mermaid diagrams, as has been explained to you in your initial instructions.
 excluded_tools: []
+included_optional_tools:
+  - switch_modes
+
 tool_description_overrides: {}
diff --git a/src/serena/resources/config/contexts/ide-assistant.yml b/src/serena/resources/config/contexts/ide-assistant.yml
index 14d65130..27a13673 100644
--- a/src/serena/resources/config/contexts/ide-assistant.yml
+++ b/src/serena/resources/config/contexts/ide-assistant.yml
@@ -19,13 +19,8 @@ prompt: |
 excluded_tools:
   - create_text_file
   - read_file
-  - delete_lines
-  - replace_lines
-  - insert_at_line
   - execute_shell_command
   - prepare_for_new_conversation
-  - summarize_changes
-  - get_current_config
 
 tool_description_overrides: {}
 
diff --git a/src/serena/resources/config/modes/mode.template.yml b/src/serena/resources/config/modes/mode.template.yml
index 431afdeb..6d836ca3 100644
--- a/src/serena/resources/config/modes/mode.template.yml
+++ b/src/serena/resources/config/modes/mode.template.yml
@@ -2,3 +2,6 @@
 description: Description of the mode, not used in the code.
 prompt: Prompt that will form part of the message sent to the model when activating this mode.
 excluded_tools: []
+
+# several tools are excluded by default and have to be explicitly included by the user
+included_optional_tools: []
\ No newline at end of file
diff --git a/src/serena/tools/cmd_tools.py b/src/serena/tools/cmd_tools.py
index 0db0da08..214d54e2 100644
--- a/src/serena/tools/cmd_tools.py
+++ b/src/serena/tools/cmd_tools.py
@@ -19,15 +19,8 @@ class ExecuteShellCommandTool(Tool, ToolMarkerCanEdit):
         max_answer_chars: int = TOOL_DEFAULT_MAX_ANSWER_LENGTH,
     ) -> str:
         """
-        Execute a shell command and return its output.
-
-        IMPORTANT: you should always consider the memory about suggested shell commands before using this tool.
-        If this memory was not loaded in the current conversation, you should load it using the `read_memory` tool
-        before using this tool.
-
-        You should have at least once looked at the suggested shell commands from the corresponding memory
-        created during the onboarding process before using this tool.
-        Never execute unsafe shell commands like `rm -rf /` or similar! Generally be very careful with deletions.
+        Execute a shell command and return its output. If there is a memory about suggested commands, read that first.
+        Never execute unsafe shell commands like `rm -rf /` or similar!
 
         :param command: the shell command to execute
         :param cwd: the working directory to execute the command in. If None, the project root will be used.
diff --git a/src/serena/tools/config_tools.py b/src/serena/tools/config_tools.py
index 51b782ad..8a3ddeb7 100644
--- a/src/serena/tools/config_tools.py
+++ b/src/serena/tools/config_tools.py
@@ -1,7 +1,7 @@
 import json
 
 from serena.config.context_mode import SerenaAgentMode
-from serena.tools import Tool, ToolMarkerDoesNotRequireActiveProject
+from serena.tools import Tool, ToolMarkerDoesNotRequireActiveProject, ToolMarkerOptional
 
 
 class ActivateProjectTool(Tool, ToolMarkerDoesNotRequireActiveProject):
@@ -35,7 +35,7 @@ class ActivateProjectTool(Tool, ToolMarkerDoesNotRequireActiveProject):
         return result_str
 
 
-class RemoveProjectTool(Tool, ToolMarkerDoesNotRequireActiveProject):
+class RemoveProjectTool(Tool, ToolMarkerDoesNotRequireActiveProject, ToolMarkerOptional):
     """
     Removes a project from the Serena configuration.
     """
@@ -50,7 +50,7 @@ class RemoveProjectTool(Tool, ToolMarkerDoesNotRequireActiveProject):
         return f"Successfully removed project '{project_name}' from configuration."
 
 
-class SwitchModesTool(Tool):
+class SwitchModesTool(Tool, ToolMarkerOptional):
     """
     Activates modes by providing a list of their names
     """
@@ -71,7 +71,7 @@ class SwitchModesTool(Tool):
         return result_str
 
 
-class GetCurrentConfigTool(Tool):
+class GetCurrentConfigTool(Tool, ToolMarkerOptional):
     """
     Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
     """
diff --git a/src/serena/tools/file_tools.py b/src/serena/tools/file_tools.py
index f79ffe06..b5770ab5 100644
--- a/src/serena/tools/file_tools.py
+++ b/src/serena/tools/file_tools.py
@@ -14,7 +14,7 @@ from fnmatch import fnmatch
 from pathlib import Path
 
 from serena.text_utils import search_files
-from serena.tools import SUCCESS_RESULT, TOOL_DEFAULT_MAX_ANSWER_LENGTH, EditedFileContext, Tool, ToolMarkerCanEdit
+from serena.tools import SUCCESS_RESULT, TOOL_DEFAULT_MAX_ANSWER_LENGTH, EditedFileContext, Tool, ToolMarkerCanEdit, ToolMarkerOptional
 from serena.util.file_system import scan_directory
 
 
@@ -29,7 +29,6 @@ class ReadFileTool(Tool):
         """
         Reads the given file or a chunk of it. Generally, symbolic operations
         like find_symbol or find_referencing_symbols should be preferred if you know which symbols you are looking for.
-        Reading the entire file is only recommended if there is no other way to get the content required for the task.
 
         :param relative_path: the relative path to the file to read
         :param start_line: the 0-based index of the first line to be retrieved.
@@ -60,14 +59,7 @@ class CreateTextFileTool(Tool, ToolMarkerCanEdit):
 
     def apply(self, relative_path: str, content: str) -> str:
         """
-        Write a new file (or overwrite an existing file). For existing files, it is strongly recommended
-        to use symbolic operations like replace_symbol_body or insert_after_symbol/insert_before_symbol, if possible.
-        You can also use insert_at_line to insert content at a specific line for existing files if the symbolic operations
-        are not the right choice for what you want to do.
-
-        If ever used on an existing file, the content has to be the complete content of that file (so it
-        may never end with something like "The remaining content of the file is left unchanged.").
-        For operations that just replace a part of a file, use the replace_lines or the symbolic editing tools instead.
+        Write a new file or overwrite an existing file.
 
         :param relative_path: the relative path to the file to create
         :param content: the (utf-8-encoded) content to write to the file
@@ -200,7 +192,7 @@ class ReplaceRegexTool(Tool, ToolMarkerCanEdit):
         return SUCCESS_RESULT
 
 
-class DeleteLinesTool(Tool, ToolMarkerCanEdit):
+class DeleteLinesTool(Tool, ToolMarkerCanEdit, ToolMarkerOptional):
     """
     Deletes a range of lines within a file.
     """
@@ -228,7 +220,7 @@ class DeleteLinesTool(Tool, ToolMarkerCanEdit):
         return SUCCESS_RESULT
 
 
-class ReplaceLinesTool(Tool, ToolMarkerCanEdit):
+class ReplaceLinesTool(Tool, ToolMarkerCanEdit, ToolMarkerOptional):
     """
     Replaces a range of lines within a file with new content.
     """
@@ -259,7 +251,7 @@ class ReplaceLinesTool(Tool, ToolMarkerCanEdit):
         return SUCCESS_RESULT
 
 
-class InsertAtLineTool(Tool, ToolMarkerCanEdit):
+class InsertAtLineTool(Tool, ToolMarkerCanEdit, ToolMarkerOptional):
     """
     Inserts content at a given line in a file.
     """
@@ -351,7 +343,7 @@ class SearchForPatternTool(Tool):
             For example, for finding classes or methods from a name pattern.
             Setting to False is a better choice if you also want to search in non-code files, like in html or yaml files,
             which is why it is the default.
-        :return: A JSON object mapping file paths to lists of matched consecutive lines (with context, if requested).
+        :return: A mapping of file paths to lists of matched consecutive lines.
         """
         abs_path = os.path.join(self.get_project_root(), relative_path)
         if not os.path.exists(abs_path):
diff --git a/src/serena/tools/memory_tools.py b/src/serena/tools/memory_tools.py
index 63bba4fe..3cf611f0 100644
--- a/src/serena/tools/memory_tools.py
+++ b/src/serena/tools/memory_tools.py
@@ -10,15 +10,8 @@ class WriteMemoryTool(Tool):
 
     def apply(self, memory_name: str, content: str, max_answer_chars: int = TOOL_DEFAULT_MAX_ANSWER_LENGTH) -> str:
         """
-        Write some information about this project that can be useful for future tasks to a memory.
-        Use markdown formatting for the content.
-        The information should be short and to the point.
-        The memory name should be meaningful, such that from the name you can infer what the information is about.
-        It is better to have multiple small memories than to have a single large one because
-        memories will be read one by one and we only ever want to read relevant memories.
-
-        This tool is either called during the onboarding process or when you have identified
-        something worth remembering about the project from the past conversation.
+        Write some information about this project that can be useful for future tasks to a memory in md format.
+        The memory name should be meaningful.
         """
         if len(content) > max_answer_chars:
             raise ValueError(
diff --git a/src/serena/tools/symbol_tools.py b/src/serena/tools/symbol_tools.py
index 4d2a5ffc..0dfb41a3 100644
--- a/src/serena/tools/symbol_tools.py
+++ b/src/serena/tools/symbol_tools.py
@@ -4,6 +4,7 @@ Language server-related tools
 
 import dataclasses
 import json
+import os
 from collections.abc import Sequence
 from copy import copy
 from typing import Any
@@ -33,10 +34,7 @@ class RestartLanguageServerTool(Tool):
 
     def apply(self) -> str:
         """Use this tool only on explicit user request or after confirmation.
-        It may be necessary to restart the language server if the user performs edits
-        not through Serena, so the language server state becomes outdated and further editing attempts lead to errors.
-
-        If such editing errors happen, you should suggest using this tool.
+        It may be necessary to restart the language server if it hangs.
         """
         self.agent.reset_language_server()
         return SUCCESS_RESULT
@@ -49,24 +47,28 @@ class GetSymbolsOverviewTool(Tool):
 
     def apply(self, relative_path: str, max_answer_chars: int = TOOL_DEFAULT_MAX_ANSWER_LENGTH) -> str:
         """
-        Gets an overview of the given file or directory.
-        For each analyzed file, we list the top-level symbols in the file (name_path, kind).
-        Use this tool to get a high-level understanding of the code symbols.
-        Calling this is often a good idea before more targeted reading, searching or editing operations on the code symbols.
-        Before requesting a symbol overview, it is usually a good idea to narrow down the scope of the overview
-        by first understanding the basic directory structure of the repository that you can get from memories
-        or by using the `list_dir` and `find_file` tools (or similar).
+        Use this tool to get a high-level understanding of the code symbols in a file.
+        This should be the first tool to call when you want to understand a new file, unless you already know
+        what you are looking for.
 
         :param relative_path: the relative path to the file or directory to get the overview of
         :param max_answer_chars: if the overview is longer than this number of characters,
             no content will be returned. Don't adjust unless there is really no other way to get the content
             required for the task. If the overview is too long, you should use a smaller directory instead,
             (e.g. a subdirectory).
-        :return: a JSON object mapping relative paths of all contained files to info about top-level symbols in the file (name_path, kind).
+        :return: a JSON object containing info about top-level symbols in the file
         """
         symbol_retriever = self.create_language_server_symbol_retriever()
-        result = symbol_retriever.get_symbol_overview(relative_path)
-        result_json_str = json.dumps({k: [dataclasses.asdict(i) for i in l] for k, l in result.items()})
+        file_path = os.path.join(self.project.project_root, relative_path)
+
+        # The symbol overview is capable of working with both files and directories,
+        # but we want to ensure that the user provides a file path.
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File or directory {relative_path} does not exist in the project.")
+        if os.path.isdir(file_path):
+            raise ValueError(f"Expected a file path, but got a directory path: {relative_path}. ")
+        result = symbol_retriever.get_symbol_overview(relative_path)[relative_path]
+        result_json_str = json.dumps([dataclasses.asdict(i) for i in result])
         return self._limit_length(result_json_str, max_answer_chars)
 
 
@@ -132,7 +134,7 @@ class FindSymbolTool(Tool):
         :param exclude_kinds: Optional. List of LSP symbol kind integers to exclude. Takes precedence over `include_kinds`.
         :param substring_matching: If True, use substring matching for the last segment of `name`.
         :param max_answer_chars: Max characters for the JSON result. If exceeded, no content is returned.
-        :return: JSON string: a list of symbols (with locations) matching the name.
+        :return: a list of symbols (with locations) matching the name.
         """
         parsed_include_kinds: Sequence[SymbolKind] | None = [SymbolKind(k) for k in include_kinds] if include_kinds else None
         parsed_exclude_kinds: Sequence[SymbolKind] | None = [SymbolKind(k) for k in exclude_kinds] if exclude_kinds else None
@@ -164,10 +166,8 @@ class FindReferencingSymbolsTool(Tool):
         max_answer_chars: int = TOOL_DEFAULT_MAX_ANSWER_LENGTH,
     ) -> str:
         """
-        Finds symbols that reference the symbol at the given `name_path`. The result will contain metadata about the referencing symbols
-        as well as a short code snippet around the reference (unless `include_body` is True, then the short snippet will be omitted).
-        Note that among other kinds of references, this function can be used to find (direct) subclasses of a class,
-        as subclasses are referencing symbols that have the kind class.
+        Finds references to the symbol at the given `name_path`. The result will contain metadata about the referencing symbols
+        as well as a short code snippet around the reference.
 
         :param name_path: for finding the symbol to find references for, same logic as in the `find_symbol` tool.
         :param relative_path: the relative path to the file containing the symbol for which to find references.
@@ -269,9 +269,9 @@ class InsertBeforeSymbolTool(Tool, ToolMarkerCanEdit):
         body: str,
     ) -> str:
         """
-        Inserts the given body/content before the beginning of the definition of the given symbol (via the symbol's location).
-        A typical use case is to insert a new class, function, method, field or variable assignment.
-        It also can be used to insert a new import statement before the first symbol in the file.
+        Inserts the given content before the beginning of the definition of the given symbol (via the symbol's location).
+        A typical use case is to insert a new class, function, method, field or variable assignment; or
+        a new import statement before the first symbol in the file.
 
         :param name_path: name path of the symbol before which to insert content (definitions in the `find_symbol` tool apply)
         :param relative_path: the relative path to the file containing the symbol
diff --git a/src/serena/tools/workflow_tools.py b/src/serena/tools/workflow_tools.py
index 38cc19be..be78d03d 100644
--- a/src/serena/tools/workflow_tools.py
+++ b/src/serena/tools/workflow_tools.py
@@ -96,7 +96,7 @@ class ThinkAboutWhetherYouAreDoneTool(Tool):
         return self.prompt_factory.create_think_about_whether_you_are_done()
 
 
-class SummarizeChangesTool(Tool):
+class SummarizeChangesTool(Tool, ToolMarkerOptional):
     """
     Provides instructions for summarizing the changes made to the codebase.
     """

From 3d8f5f7446508bd5cd68db826b66109ffa685524 Mon Sep 17 00:00:00 2001
From: MischaPanch <mischa.panch@gmail.com>
Date: Sun, 3 Aug 2025 00:14:23 +0200
Subject: [PATCH 7/7] Added chatgpt context

---
 .../resources/config/contexts/chatgpt.yml     | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 src/serena/resources/config/contexts/chatgpt.yml

diff --git a/src/serena/resources/config/contexts/chatgpt.yml b/src/serena/resources/config/contexts/chatgpt.yml
new file mode 100644
index 00000000..c758b2c3
--- /dev/null
+++ b/src/serena/resources/config/contexts/chatgpt.yml
@@ -0,0 +1,28 @@
+description: A configuration specific for chatgpt, which has a limit of 30 tools and requires short descriptions.
+prompt: |
+  You are running in desktop app context where the tools give you access to the code base as well as some
+  access to the file system, if configured. You interact with the user through a chat interface that is separated
+  from the code base. As a consequence, if you are in interactive mode, your communication with the user should
+  involve high-level thinking and planning as well as some summarization of any code edits that you make.
+  For viewing the code edits the user will view them in a separate code editor window, and the back-and-forth
+  between the chat and the code editor should be minimized as well as facilitated by you.
+  If complex changes have been made, advise the user on how to review them in the code editor.
+  If complex relationships that the user asked for should be visualized or explained, consider creating
+  a diagram in addition to your text-based communication. Note that in the chat interface you have various rendering
+  options for text, html, and mermaid diagrams, as has been explained to you in your initial instructions.
+excluded_tools: []
+included_optional_tools:
+  - switch_modes
+
+tool_description_overrides:
+  find_symbol: |
+    Retrieves symbols matching `name_path` in a file.
+    Use `depth > 0` to include children. `name_path` can be: "foo": any symbol named "foo"; "foo/bar": "bar" within "foo"; "/foo/bar": only top-level "foo/bar"
+  replace_regex: |
+    Replaces text using regular expressions. Preferred for smaller edits where symbol-level tools aren't appropriate.
+    Use wildcards (.*?) to match large sections efficiently: "beginning.*?end" instead of specifying exact content.
+    Essential for multi-line replacements.
+  search_for_pattern: |
+    Flexible pattern search across codebase. Prefer symbolic operations when possible.
+    Uses DOTALL matching. Use non-greedy quantifiers (.*?) to avoid over-matching.
+    Supports file filtering via globs and code-only restriction.
\ No newline at end of file