Tools and APIs

Tools and APIs#

Serena provides an agent (LLM) with its functionality through one of two interfaces (configured in Serena’s global configuration):

  • Tools (the classic interface): every operation is a separate tool of the MCP server.

  • REPL (new in Serena v2): a single tool executes Python code, through which the agent accesses the operations programmatically. The agent can thus combine several operations in one call, process the results in code and return only the information it actually needs.

While both interfaces offer the same general functionality for the most part, the REPL interface addresses several limitations inherent in the tool-based approach (see advantages below).

Note

The Serena REPL is an unreleased BETA feature. Please provide feedback; if you encounter issues, report them.

Tools (Classic Interface)#

Find the full list of Serena’s tools below.

Note that in most configurations, only a subset of these tools will be enabled simultaneously. Tools marked as optional are disabled by default.

Tools marked as [BETA] were recently introduced and may not be fully robust yet.

  • symbol_tools

    • find_declaration: Finds the declaration/definition of a symbol

    • find_implementations: Finds the implementations of a symbol

    • find_referencing_symbols: Finds symbols that reference the given symbol

    • find_symbol: Performs a global (or local) search using the language server backend.

    • get_diagnostics_for_file: Gets diagnostics for a file, grouped by symbol.

    • get_diagnostics_for_symbol (optional): Gets diagnostics for a symbol and, optionally, for symbols that reference it.

    • 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.

    • rename_symbol: Renames a symbol throughout the codebase using language server refactoring capabilities. For JB, we use a separate tool.

    • replace_symbol_body: Replaces the full definition of a symbol using the language server backend.

    • restart_language_server (optional): Restarts the language server(s).

    • safe_delete_symbol:

  • jetbrains_tools

    • jet_brains_debug (optional): Provides debugging functionality (run configs, breakpoints, stepping, inspection, and evaluation) via a persistent debug REPL connected to the JetBrains IDE.

    • jet_brains_find_declaration (optional): Finds the declaration of a symbol using the JetBrains backend

    • jet_brains_find_implementations (optional): Finds the implementations of a symbol using the JetBrains backend

    • jet_brains_find_referencing_symbols (optional): Finds symbols that reference the given symbol using the JetBrains backend

    • jet_brains_find_symbol (optional): Performs a global (or local) search for symbols using the JetBrains backend

    • jet_brains_get_symbols_overview (optional): Retrieves an overview of the top-level symbols within a specified file using the JetBrains backend

    • jet_brains_inline_symbol (optional): Inlines a symbol using the JetBrains backend, replacing all call sites with the symbol’s body

    • jet_brains_list_inspections (optional): Lists available JetBrains IDE inspections, optionally filtered by language or group.

    • jet_brains_move (optional): Moves a symbol, file or directory to a new location using the JetBrains backend, updating all references

    • jet_brains_rename (optional): Renames a symbol, file or directory throughout the codebase using the JetBrains backend.

    • jet_brains_run_inspections (optional): Runs JetBrains IDE inspections on a file and returns the results.

    • jet_brains_safe_delete (optional): Safely deletes a symbol using the JetBrains backend, checking for remaining usages first

    • jet_brains_type_hierarchy (optional): Retrieves the type hierarchy (supertypes and/or subtypes) of a symbol using the JetBrains backend

  • cmd_tools

    • execute_shell_command: Executes a shell command.

  • config_tools

    • activate_project: Activates a project based on the project name or path.

    • get_current_config: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.

    • open_dashboard (optional): Opens the Serena web dashboard in the default web browser. The dashboard provides logs, session information, and tool usage statistics.

    • remove_project (optional): Removes a project from the Serena configuration.

  • file_tools

    • create_text_file: Creates/overwrites a file in the project directory.

    • delete_lines (optional): Deletes a range of lines within a file.

    • find_file: Finds files in the given relative paths

    • insert_at_line (optional): Inserts content at a given line in a file.

    • list_dir: Lists files and directories in the given directory (optionally with recursion).

    • read_file: Reads a file within the project directory.

    • replace_content: Replaces content in a file (optionally using regular expressions).

    • replace_in_files: Replaces occurrences of a pattern across multiple files, with dry-run preview and per-occurrence selection.

    • replace_lines (optional): Replaces a range of lines within a file with new content.

    • search_for_pattern:

  • memory_tools

    • delete_memory: Delete a memory file.

    • edit_memory: Replaces content matching a regular expression in a memory.

    • list_memories: Lists available memories.

    • read_memory: Reads the content of a memory file.

    • rename_memory: Renames or moves a memory, updating references that are marked with the mem: prefix.

    • write_memory: Write some information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format. The memory name should be meaningful.

  • query_project_tools

    • list_queryable_projects (optional): Tool for listing all projects that can be queried by the QueryProjectTool.

    • query_project (optional): Tool for querying external project information (i.e. information from projects other than the current one), by executing a read-only tool.

  • repl_tools

    • serena_repl (optional) [BETA]: Executes Python code which accesses Serena’s functionality programmatically.

  • workflow_tools

    • initial_instructions: Provides instructions Serena usage (i.e. the ‘Serena Instructions Manual’) for clients that do not read the initial instructions when the MCP server is connected.

    • onboarding: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).

    • serena_info (optional): Provides information about an advanced topic on demand, facilitating context-efficiency.

Serena’s REPL (Code Execution-Based Interface)#

With the REPL interface, the agent uses a single tool, which executes Python code. The code accesses Serena’s functionality through the entrypoint object s, whose attributes are facades, each of which groups the operations of one domain. For instance, this code finds a class and returns the names of its members in a single call:

result = s.lsp.find_symbol("SerenaAgent", depth=1)
[member.name for member in result.symbols[0].iter_children()]

The agent retrieves the details it requires (signatures, documentation, result types) at runtime via s.info(...) (principle of progressive disclosure).

As with tools, only a subset of the operations is available in a given configuration:

  • The facades lsp and jb are mutually exclusive, being tied to the respective language backend.

  • Operations marked as optional, as well as all operations of facades marked as optional, are disabled by default and must be enabled explicitly.

Advantages#

  • Composition: The agent can combine several operations in a single call, using control flow, filtering and aggregation. Multi-step retrievals that would otherwise require a series of round-trips (find a symbol, inspect its members, find their references) become one call.

  • Context economy: Only the result the agent actually needs enters the conversation. Intermediate results remain in the Python runtime instead of consuming the context window — which, for large result sets, is the difference between a summary and thousands of tokens.

  • Results as objects: Operations return objects which can be processed programmatically rather than plain text.

  • Progressive disclosure: Instead of the schemas of dozens of tools, the agent is given a list of the available operations, retrieving the details it requires (signatures, documentation, result types) on demand. This eliminates the need for a client-specific tool search/dynamic tool discovery mechanism.

  • Reusability within a session: Variables and helper functions defined by the agent persist across calls, allowing intermediate results to be revisited and recurring logic to be applied repeatedly.

  • Dynamic adaptation: The set of available operations can change at runtime. For MCP tools, changes to the toolset are not widely supported by clients and are therefore not applied; within the REPL, the operations can follow the current situation. This is what allows the language backend to be switched during a session, e.g. when a project whose configuration demands a different backend is activated..

List of Facades#

  • lsp: symbol-level operations on the codebase backed by language servers

    • lsp.find_declaration: Finds the declaration of a symbol based on an occurrence of the symbol in a source file, specified by a regex.

    • lsp.find_implementations: Finds implementations of the symbol at the given name_path.

    • lsp.find_referencing_symbols: Finds references to the symbol at the given name_path.

    • lsp.find_symbol: Finds symbols and code entities (classes, methods, etc.) based on the given name path pattern.

    • lsp.get_diagnostics_for_file: Gets diagnostics for a file.

    • lsp.get_diagnostics_for_symbol (optional): Gets diagnostics for the specified symbol.

    • lsp.get_symbols_overview: Gets an overview of the symbols defined in the given file (classes, methods, fields, functions, etc.)

    • lsp.rename_symbol: Renames the symbol with the given name_path to new_name throughout the entire codebase.

    • lsp.restart_language_server (optional): Restarts the language server(s).

    • lsp.safe_delete_symbol: Deletes the symbol if it is safe to do so (i.e., if there are no references to it)

  • jb: operations on the codebase backed by the JetBrains IDE’s code intelligence

    • jb.debug_eval: Provides debugging functionality (run configs, breakpoints, stepping, inspection, and evaluation)

    • jb.debug_eval_info: Provides usage information for the debug REPL (method debug_eval)

    • jb.find_declaration: Finds the declaration of a symbol based on an occurrence of the symbol in a source file, specified by a regex.

    • jb.find_implementations: Finds the implementations of a symbol.

    • jb.find_referencing_symbols: Finds all symbols that reference the given symbol (its callers / usages / dependents)

    • jb.find_symbol: Finds symbols and code entities (classes, methods, etc.) based on the given name path pattern.

    • jb.get_symbols_overview: Gets an overview of the top-level symbols defined in the given file (classes, methods, fields).

    • jb.get_type_hierarchy: Gets the type hierarchy of a symbol (supertypes, subtypes, or both).

    • jb.inline_symbol [BETA]: Inlines a symbol, replacing all call sites with the symbol’s body.

    • jb.list_inspections: Lists available IDE inspections.

    • jb.move [BETA]: Moves a symbol, file or directory to a different location and automatically updates all references to affected symbols.

    • jb.rename: Renames a symbol, file or directory throughout the codebase.

    • jb.run_inspections: Runs IDE inspections (code analysis) on the given file and returns the problems found.

    • jb.safe_delete [BETA]: Safely deletes a symbol, file, or directory, checking for usages first and propagating deletion, if desired.

  • cfg: Serena’s configuration and session state (incl. the dashboard)

    • cfg.get_current_config: Provides the current configuration of the agent, including the active and available projects, tools, contexts, and modes.

    • cfg.open_dashboard: Opens the Serena web dashboard in the default web browser.

  • fs: the project’s files as units (as opposed to their content, see edit)

    • fs.create_text_file: Writes a new file or overwrites an existing file with the given content.

    • fs.find_file: Finds files matching the given file mask within the given relative path.

    • fs.list_dir: Lists files and directories in the given directory (optionally with recursion).

    • fs.read_file: Reads the given file or a range of its lines.

    • fs.search_for_pattern: Searches for a regex pattern across project files, returning whole matched lines (plus optional context).

  • edit: modifying content within existing files (independent of the language backend)

    • edit.delete_lines (optional): Deletes the given lines in the file.

    • edit.insert_after_symbol: Inserts code after a class/method/function definition.

    • edit.insert_at_line (optional): Inserts the given content at the given line in the file, pushing existing content of the line down.

    • edit.insert_before_symbol: Inserts the given content before the beginning of the definition of the given symbol (via the symbol’s location).

    • edit.replace_content: Replaces one or more occurrences of a given pattern in a file with new content.

    • edit.replace_in_files: Replaces occurrences of a pattern across multiple files in ONE call.

    • edit.replace_lines (optional): Replaces the given range of lines in the given file.

    • edit.replace_symbol_body: Replaces the body of the given symbol.

  • mem: project memories, i.e. persistent notes for future tasks

    • mem.delete_memory: Deletes a memory; only call this if instructed explicitly or permission was granted by the user.

    • mem.edit_memory: Replaces content matching a pattern in a memory.

    • mem.list_memories: Lists the available memories, optionally filtered by topic.

    • mem.onboarding: Provides the instructions for performing onboarding (identifying the project structure and essential tasks,

    • mem.read_memory: Reads a memory.

    • mem.rename_memory: Renames or moves a memory; use “/” in the name to organize into topics.

    • mem.write_memory: Writes information (about the active project) to a memory.

  • shell: execution of shell commands

    • shell.execute_shell_command: Executes a shell command and returns its output. If there is a memory about suggested commands, read that first.

  • ext (optional): read-only access to external projects (projects other than the active one)

    • ext.list_projects: Lists the registered projects which can be queried.

    • ext.project_context (optional): Provides a context (for use in a with statement) within which all facades operate on the given external project

    • ext.read_project_context: Provides a context (for use in a with statement) within which all facades operate on the given external project

Contents