Move tool list to docs, restructure README

Author: opcode81

README.md

@@ -24,11 +24,9 @@ Instead, it can use code-centric tools like `find_symbol`, `find_referencing_sym
 
 ### LLM Integration
 
-Serena provides the necessary [tools](#list-of-tools) for coding workflows, but an LLM is required to do the actual work,
+Serena provides the necessary [tools](https://oraios.github.io/serena/01-about/035_tools.html) for coding workflows, but an LLM is required to do the actual work,
 orchestrating tool use.
 
-For example, **supercharge the performance of Claude Code** with a [one-line shell command](#claude-code).
-
 In general, Serena can be integrated with an LLM in several ways:
 
 * by using the **model context protocol (MCP)**.
@@ -79,13 +77,32 @@ AL, Bash, C#, C/C++, Clojure, Dart, Elixir, Elm, Erlang, Fortran, Go, Haskell, J
 > Support for further languages can easily be added by providing a shallow adapter for a new language server implementation,
 > see Serena's [memory on that](.serena/memories/adding_new_language_support_guide.md).
 
+## Quick Start
+
+Serena is managed with **uv**. If you don’t already have it installed, you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/).
+
+To get started as quickly as possible, you can directly enable the Serena MCP server in your client of choice (by following the links provided): 
+
+* For coding with Claude, we recommend using Serena through [Claude Code](https://oraios.github.io/serena/02-usage/030_clients.html#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in [Codex](https://oraios.github.io/serena/02-usage/030_clients.html#codex) and a wide variety of [other clients](https://oraios.github.io/serena/02-usage/030_clients.html#other-clients).
+* If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](https://oraios.github.io/serena/02-usage/030_clients.html#local-guis-and-agent-frameworks) that support MCP servers.
+  You can also connect Serena to many web clients (including ChatGPT) using [mcpo](https://oraios.github.io/serena/03-special-guides/serena_on_chatgpt.html).
+* If you want to integrate Serena with your IDE, see the section on [other MCP clients](https://oraios.github.io/serena/02-usage/030_clients.html#mcp-enabled-ides-and-coding-clients-cline-roo-code-cursor-windsurf-etc).
+
+> [!TIP]
+> While getting started quickly is easy, Serena is a powerful toolkit with many configuration options.
+> We highly recommend reading through the [user guide](https://oraios.github.io/serena/) to get the most out of Serena.
+
+## User Guide
+
+Please refer to the [user guide](https://oraios.github.io/serena/) for detailed instructions on how to use Serena effectively.
+
 ### Community Feedback
 
 Most users report that Serena has strong positive effects on the results of their coding agents, even when used within
 very capable agents like Claude Code. Serena is often described to be a [game changer](https://www.reddit.com/r/ClaudeAI/comments/1lfsdll/try_out_serena_mcp_thank_me_later/), providing an enormous [productivity boost](https://www.reddit.com/r/ClaudeCode/comments/1mguoia/absolutely_insane_improvement_of_claude_code).
 
 Serena excels at navigating and manipulating complex codebases, providing tools that support precise code retrieval and editing in the presence of large, strongly structured codebases.
-However, when dealing with tasks that involve only very few/small files, you may not benefit from including Serena on top of your existing coding agent. 
+However, when dealing with tasks that involve only very few/small files, you may not benefit from including Serena on top of your existing coding agent.
 In particular, when writing code from scratch, Serena will not provide much value initially, as the more complex structures that Serena handles more gracefully than simplistic, file-based approaches are yet to be created.
 
 Several videos and blog posts have talked about Serena:
@@ -100,25 +117,6 @@ Several videos and blog posts have talked about Serena:
     * [Serena with Claude Code (in Japanese)](https://blog.lai.so/serena/)
     * [Turning Claude Code into a Development Powerhouse](https://robertmarshall.dev/blog/turning-claude-code-into-a-development-powerhouse/)
 
-## Quick Start
-
-Serena is managed with **uv**. If you don’t already have it installed, you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/).
-
-To get started as quickly as possible, you can directly enable the Serena MCP server in your client of choice (by following the links provided): 
-
-* For coding with Claude, we recommend using Serena through [Claude Code](https://oraios.github.io/serena/02-usage/030_clients.html#claude-code) or [Claude Desktop](#claude-desktop). You can also use Serena in [Codex](https://oraios.github.io/serena/02-usage/030_clients.html#codex) and a wide variety of [other clients](https://oraios.github.io/serena/02-usage/030_clients.html#other-clients).
-* If you want a GUI experience outside an IDE, you can use one of the many [local GUIs](https://oraios.github.io/serena/02-usage/030_clients.html#local-guis-and-agent-frameworks) that support MCP servers.
-  You can also connect Serena to many web clients (including ChatGPT) using [mcpo](https://oraios.github.io/serena/03-special-guides/serena_on_chatgpt.html).
-* If you want to integrate Serena with your IDE, see the section on [other MCP clients](https://oraios.github.io/serena/02-usage/030_clients.html#mcp-enabled-ides-and-coding-clients-cline-roo-code-cursor-windsurf-etc).
-
-> [!TIP]
-> While getting started quickly is easy, Serena is a powerful toolkit with many configuration options.
-> We highly recommend reading through the [user guide](https://oraios.github.io/serena/) to get the most out of Serena.
-
-## User Guide
-
-Please refer to the [user guide](https://oraios.github.io/serena/) for detailed instructions on how to use Serena effectively.
-
 ## Acknowledgements
 
 ### Sponsors
@@ -148,16 +146,12 @@ what it is today.
 We built Serena on top of multiple existing open-source technologies, the most important ones being:
 
 1. [multilspy](https://github.com/microsoft/multilspy).
-   A library which wraps language server implementations and adapts them for interaction via Python
-   and which provided the basis for our library Solid-LSP (src/solidlsp).
+   A library which wraps language server implementations and adapts them for interaction via Python.
+   It provided the basis for our library Solid-LSP (`src/solidlsp`).
    Solid-LSP provides pure synchronous LSP calls and extends the original library with the symbolic logic
    that Serena required.
 2. [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
-3. [Agno](https://github.com/agno-agi/agno) and
-   the associated [agent-ui](https://github.com/agno-agi/agent-ui),
-   which we use to allow Serena to work with any model, beyond the ones
-   supporting the MCP.
-4. All the language servers that we use through Solid-LSP.
+3. All the language servers that we use through Solid-LSP.
 
 Without these projects, Serena would not have been possible (or would have been significantly more difficult to build).
 
@@ -173,54 +167,3 @@ It is also relatively straightforward to add [support for a new programming lang
 
 We look forward to seeing what the community will come up with!
 For details on contributing, see [contributing guidelines](/CONTRIBUTING.md).
-
-## List of Tools
-
-Here is the list of Serena's default tools with a short description (output of `uv run serena tools list`):
-
-* `activate_project`: Activates a project based on the project name or path.
-* `check_onboarding_performed`: Checks whether project onboarding was already performed.
-* `create_text_file`: Creates/overwrites a file in the project directory.
-* `delete_memory`: Deletes a memory from Serena's project-specific memory store.
-* `execute_shell_command`: Executes a shell command.
-* `find_file`: Finds files in the given relative paths
-* `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
-* `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
-* `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-* `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-* `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-* `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
-* `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-* `list_memories`: Lists memories in Serena's project-specific memory store.
-* `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-* `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
-* `read_file`: Reads a file within the project directory.
-* `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
-* `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities.
-* `replace_regex`: Replaces content in a file by using regular expressions.
-* `replace_symbol_body`: Replaces the full definition of a symbol.
-* `search_for_pattern`: Performs a search for a pattern in the project.
-* `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
-* `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
-* `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
-* `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
-
-There are several tools that are disabled by default, and have to be enabled explicitly, e.g., through the context or modes.
-Note that several of our default contexts do enable some of these tools. For example, the `desktop-app` context enables the `execute_shell_command` tool.
-
-The full list of optional tools is (output of `uv run serena tools list --only-optional`):
-
-* `delete_lines`: Deletes a range of lines within a file.
-* `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-* `initial_instructions`: Gets the initial instructions for the current project.
-    Should only be used in settings where the system prompt cannot be set,
-    e.g. in clients you have no control over, like Claude Desktop.
-* `insert_at_line`: Inserts content at a given line in a file.
-* `jet_brains_find_referencing_symbols`: Finds symbols that reference the given symbol
-* `jet_brains_find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
-* `jet_brains_get_symbols_overview`: Retrieves an overview of the top-level symbols within a specified file
-* `remove_project`: Removes a project from the Serena configuration.
-* `replace_lines`: Replaces a range of lines within a file with new content.
-* `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
-* `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
-* `switch_modes`: Activates modes by providing a list of their names

docs/01-about/035_tools.md

@@ -0,0 +1,47 @@
+## List of Tools
+
+Find the full list of Serena's tools below (output of `<serena> tools list --all`).
+
+Note that in most configurations, only a subset of these tools will be enabled simultaneously (see the section on [configuration](../02-usage/050_configuration) for details).
+
+* `activate_project`: Activates a project based on the project name or path.
+* `check_onboarding_performed`: Checks whether project onboarding was already performed.
+* `create_text_file`: Creates/overwrites a file in the project directory.
+* `delete_lines`: Deletes a range of lines within a file.
+* `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+* `execute_shell_command`: Executes a shell command.
+* `find_file`: Finds files in the given relative paths
+* `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+* `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filter
+  ed by type).
+* `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools,
+  contexts, and modes.
+* `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+* `initial_instructions`: Provides instructions on how to use the Serena toolbox.
+* `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+* `insert_at_line`: Inserts content at a given line in a file.
+* `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+* `jet_brains_find_referencing_symbols`: Finds symbols that reference the given symbol
+* `jet_brains_find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (option
+  ally filtered by type).
+* `jet_brains_get_symbols_overview`: Retrieves an overview of the top-level symbols within a specified file
+* `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+* `list_memories`: Lists memories in Serena's project-specific memory store.
+* `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+* `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with th
+  e necessary context).
+* `read_file`: Reads a file within the project directory.
+* `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+* `remove_project`: Removes a project from the Serena configuration.
+* `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities.
+* `replace_lines`: Replaces a range of lines within a file with new content.
+* `replace_regex`: Replaces content in a file by using regular expressions.
+* `replace_symbol_body`: Replaces the full definition of a symbol.
+* `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+* `search_for_pattern`: Performs a search for a pattern in the project.
+* `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+* `switch_modes`: Activates modes by providing a list of their names
+* `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+* `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+* `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+* `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.