Allows connecting to ChatGPT via mcpo to enable tool calling for code editing and retrieval, leveraging Serena's semantic code understanding.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Serena MCP Server Find all references to the 'Config' class"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
:rocket: Serena is a powerful coding agent toolkit capable of turning an LLM into a fully-featured agent that works directly on your codebase. Unlike most other tools, it is not tied to an LLM, framework or an interface, making it easy to use it in a variety of ways.
:wrench: Serena provides essential semantic code retrieval and editing tools that are akin to an IDE's capabilities, extracting code entities at the symbol level and exploiting relational structure. When combined with an existing coding agent, these tools greatly enhance (token) efficiency.
:free: Serena is free & open-source, enhancing the capabilities of LLMs you already have access to free of charge.
You can think of Serena as providing IDE-like tools to your LLM/coding agent. With it, the agent no longer needs to read entire
files, perform grep-like searches or string replacements to find and edit the right code. Instead, it can use code centered tools like find_symbol, find_referencing_symbols and insert_after_symbol.
Serena provides the necessary tools 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.
In general, Serena can be integrated with an LLM in several ways:
by using the model context protocol (MCP). Serena provides an MCP server which integrates with
by using mcpo to connect it to ChatGPT or other clients that don't support MCP but do support tool calling via OpenAPI.
by incorporating Serena's tools into an agent framework of your choice, as illustrated here. Serena's tool implementation is decoupled from the framework-specific code and can thus easily be adapted to any agent framework.
A demonstration of Serena efficiently retrieving and editing code within Claude Code, thereby saving tokens and time. Efficient operations are not only useful for saving costs, but also for generally improving the generated code's quality. This effect may be less pronounced in very small projects, but often becomes of crucial importance in larger ones.
https://github.com/user-attachments/assets/ab78ebe0-f77d-43cc-879a-cc399efefd87
A demonstration of Serena implementing a small feature for itself (a better log GUI) with Claude Desktop. Note how Serena's tools enable Claude to find and edit the right symbols.
https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753
Serena's semantic code analysis capabilities build on language servers using the widely implemented language server protocol (LSP). The LSP provides a set of versatile code querying and editing functionalities based on symbolic understanding of the code. Equipped with these capabilities, Serena discovers and edits code just like a seasoned developer making use of an IDE's capabilities would. Serena can efficiently find the right context and do the right thing even in very large and complex projects! So not only is it free and open-source, it frequently achieves better results than existing solutions that charge a premium.
Language servers provide support for a wide range of programming languages. With Serena, we provide direct, out-of-the-box support for:
Python
TypeScript/Javascript
PHP (uses Intelephense LSP; set INTELEPHENSE_LICENSE_KEY environment variable for premium features)
Go (requires installation of gopls)
R (requires installation of the languageserver R package)
Rust (requires rustup - uses rust-analyzer from your toolchain)
C/C++ (you may experience issues with finding references, we are working on it)
Zig (requires installation of ZLS - Zig Language Server)
C#
Ruby (by default, uses ruby-lsp, specify ruby_solargraph as your language to use the previous solargraph based implementation)
Swift
Kotlin (uses the pre-alpha official kotlin LS, some issues may appear)
Java (Note: startup is slow, initial startup especially so. There may be issues with java on macos and linux, we are working on it.)
Clojure
Dart
Bash
Lua (automatically downloads lua-language-server if not installed)
Nix (requires nixd installation)
Elixir (requires installation of NextLS and Elixir; Windows not supported)
Erlang (requires installation of beam and erlang_ls, experimental, might be slow or hang)
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.
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, providing an enormous productivity boost.
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. 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:
YouTube:
Blog posts:
Related MCP server: LSP-MCP
Serena can be used in various ways, below you will find instructions for selected integrations.
For coding with Claude, we recommend using Serena through Claude Code or Claude Desktop. You can also use Serena in most other terminal-based clients.
If you want a GUI experience outside an IDE, you can use one of the many local GUIs that support MCP servers. You can also connect Serena to many web clients (including ChatGPT) using mcpo.
If you want to use Serena integrated in your IDE, see the section on other MCP clients.
You can use Serena as a library for building your own applications. We try to keep the public API stable, but you should still expect breaking changes and pin Serena to a fixed version if you use it as a dependency.
Serena is managed by uv, so you will need to install it).
You have several options for running the MCP server, which are explained in the subsections below.
The typical usage involves the client (Claude Code, Claude Desktop, etc.) running the MCP server as a subprocess (using stdio communication), so the client needs to be provided with the command to run the MCP server. (Alternatively, you can run the MCP server in SSE mode and tell your client how to connect to it.)
Note that no matter how you run the MCP server, Serena will, by default, start a small web-based dashboard on localhost that will display logs and allow shutting down the MCP server (since many clients fail to clean up processes correctly). This and other settings can be adjusted in the configuration and/or by providing command-line arguments.
uvx can be used to run the latest version of Serena directly from the repository, without an explicit local installation.
uvx --from git+https://github.com/oraios/serena serena start-mcp-serverExplore the CLI to see some of the customization options that serena provides (more info on them below).
Clone the repository and change into it.
git clone https://github.com/oraios/serena
cd serenaOptionally edit the configuration file in your home directory with
uv run serena config editIf you just want the default config, you can skip this part, and a config file will be created when you first run Serena.
Run the server with uv:
uv run serena start-mcp-serverWhen running from outside the serena installation directory, be sure to pass it, i.e., use
uv run --directory /abs/path/to/serena serena start-mcp-server⚠️ Docker support is currently experimental with several limitations. Please read the Docker documentation for important caveats before using it.
You can run the Serena MCP server directly via docker as follows,
assuming that the projects you want to work on are all located in /path/to/your/projects:
docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdioReplace /path/to/your/projects with the absolute path to your projects directory. The Docker approach provides:
Better security isolation for shell command execution
No need to install language servers and dependencies locally
Consistent environment across different systems
Alternatively, use docker compose with the compose.yml file provided in the repository.
See the Docker documentation for detailed setup instructions, configuration options, and known limitations.
If you are using Nix and have enabled the nix-command and flakes features, you can run Serena using the following command:
nix run github:oraios/serena -- start-mcp-server --transport stdioYou can also install Serena by referencing this repo (github:oraios/serena) and using it in your Nix flake. The package is exported as serena.
ℹ️ Note that MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server necessarily has to be started by the client in order for communication to take place via the server's standard input/output stream. In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and therefore needs to be configured with a launch command.
When using instead the SSE mode, which uses HTTP-based communication, you control the server lifecycle yourself, i.e. you start the server and provide the client with the URL to connect to it.
Simply provide start-mcp-server with the --transport sse option and optionally provide the port.
For example, to run the Serena MCP server in SSE mode on port 9121 using a local installation,
you would run this command from the Serena directory,
uv run serena start-mcp-server --transport sse --port 9121and then configure your client to connect to http://localhost:9121/sse.
The Serena MCP server supports a wide range of additional command-line options, including the option to run in SSE mode and to adapt Serena to various contexts and modes of operation.
Run with parameter --help to get a list of available options.
Serena is very flexible in terms of configuration. While for most users, the default configurations will work,
you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions
(what we denote as the system_prompt), adjust the output of tools that just provide a prompt, and even adjust tool descriptions.
Serena is configured in four places:
The serena_config.yml for general settings that apply to all clients and projects.
It is located in your user directory under .serena/serena_config.yml.
If you do not explicitly create the file, it will be auto-generated when you first run Serena.
You can edit it directly or use
uvx --from git+https://github.com/oraios/serena serena config edit(or use the --directory command version).
In the arguments passed to the start-mcp-server in your client's config (see below),
which will apply to all sessions started by the respective client. In particular, the context parameter
should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client.
See for a detailed explanation. You can override all entries from the serena_config.yml through command line arguments.
In the .serena/project.yml file within your project. This will hold project-level configuration that is used whenever
that project is activated. This file will be autogenerated when you first use Serena on that project, but you can also
generate it explicitly with
uvx --from git+https://github.com/oraios/serena serena project generate-yml(or use the --directory command version).
Through the context and modes. Explore the modes and contexts section for more details.
After the initial setup, continue with one of the sections below, depending on how you want to use Serena.
If you are mostly working with the same project, you can configure to always activate it at startup
by passing --project <path_or_name> to the start-mcp-server command in your client's MCP config.
This is especially useful for clients which configure MCP servers on a per-project basis, like Claude Code.
Otherwise, the recommended way is to just ask the LLM to activate a project by providing it an absolute path to, or, in case the project was activated in the past, by its name. The default project name is the directory name.
"Activate the project /path/to/my_project"
"Activate the project my_project"
All projects that have been activated will be automatically added to your serena_config.yml, and for each
project, the file .serena/project.yml will be generated. You can adjust the latter, e.g., by changing the name
(which you refer to during the activation) or other options. Make sure to not have two different projects with the
same name.
ℹ️ For larger projects, we recommend that you index your project to accelerate Serena's tools; otherwise the first tool application may be very slow. To do so, run this from the project directory (or pass the path to the project as an argument):
uvx --from git+https://github.com/oraios/serena serena project index(or use the --directory command version).
Serena is a great way to make Claude Code both cheaper and more powerful!
From your project directory, add serena with a command like this,
claude mcp add serena -- <serena-mcp-server> --context ide-assistant --project $(pwd)where <serena-mcp-server> is your way of running the Serena MCP server.
For example, when using uvx, you would run
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)ℹ️ Serena comes with an instruction text, and Claude needs to read it to properly use Serena's tools.
As of version v1.0.52, claude code reads the instructions of the MCP server, so this is handled automatically.
If you are using an older version, or if Claude fails to read the instructions, you can ask it explicitly
to "read Serena's initial instructions" or run /mcp__serena__initial_instructions to load the instruction text.
If you want to make use of that, you will have to enable the corresponding tool explicitly by adding initial_instructions to the included_optional_tools
in your config.
Note that you may have to make Claude read the instructions when you start a new conversation and after any compacting operation to ensure Claude remains properly configured to use Serena's tools.
Serena works with OpenAI's Codex CLI out of the box, but you have to use the codex context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.).
Unlike Claude Code, in Codex you add an MCP server globally and not per project. Add the following to
~/.codex/config.toml (create the file if it does not exist):
[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]After codex has started, you need to activate the project, which you can do by saying:
"Activate the current dir as project using serena"
If you don't activate the project, you will not be able to use Serena's tools!
That's it! Have a look at ~/.codex/log/codex-tui.log to see if any errors occurred.
The Serena dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing the webbrowser
may not open automatically. You can open it manually by going to http://localhost:24282/dashboard/index.html (or a higher port, if
that was already taken).
Codex will often show the tools as
failedeven though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected.
There are many terminal-based coding assistants that support MCP servers, such as Codex, Gemini-CLI, Qwen3-Coder, rovodev, the OpenHands CLI and opencode.
They generally benefit from the symbolic tools provided by Serena. You might want to customize some aspects of Serena by writing your own context, modes or prompts to adjust it to your workflow, to other MCP servers you are using, and to the client's internal capabilities.
For Claude Desktop (available for Windows and macOS), go to File / Settings / Developer / MCP Servers / Edit Config,
which will let you open the JSON file claude_desktop_config.json.
Add the serena MCP server configuration, using a run command depending on your setup.
local installation:
{
"mcpServers": {
"serena": {
"command": "/abs/path/to/uv",
"args": ["run", "--directory", "/abs/path/to/serena", "serena", "start-mcp-server"]
}
}
}uvx:
{
"mcpServers": {
"serena": {
"command": "/abs/path/to/uvx",
"args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"]
}
}
}docker:
{
"mcpServers": {
"serena": {
"command": "docker",
"args": ["run", "--rm", "-i", "--network", "host", "-v", "/path/to/your/projects:/workspaces/projects", "ghcr.io/oraios/serena:latest", "serena", "start-mcp-server", "--transport", "stdio"]
}
}
}If you are using paths containing backslashes for paths on Windows
(note that you can also just use forward slashes), be sure to escape them correctly (\\).
That's it! Save the config and then restart Claude Desktop. You are ready for activating your first project.
ℹ️ You can further customize the run command using additional arguments (see above).
Note: on Windows and macOS there are official Claude Desktop applications by Anthropic, for Linux there is an open-source community version.
⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows.
⚠️ Some clients may leave behind zombie processes. You will have to find and terminate them manually then. With Serena, you can activate the dashboard to prevent unnoted processes and also use the dashboard for shutting down Serena.
After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon).
For more information on MCP servers with Claude Desktop, see the official quick start guide.
Being an MCP Server, Serena can be included in any MCP Client. The same configuration as above,
perhaps with small client-specific modifications, should work. Most of the popular
existing coding assistants (IDE extensions or VSCode-like IDEs) support connections
to MCP Servers. It is recommended to use the ide-assistant context for these integrations by adding "--context", "ide-assistant" to the args in your MCP client's configuration. Including Serena generally boosts their performance
by providing them tools for symbolic operations.
In this case, the billing for the usage continues to be controlled by the client of your choice (unlike with the Claude Desktop client). But you may still want to use Serena through such an approach, e.g., for one of the following reasons:
You are already using a coding assistant (say Cline or Cursor) and just want to make it more powerful.
You are on Linux and don't want to use the community-created Claude Desktop.
You want tighter integration of Serena into your IDE and don't mind paying for that.
Over the last months, several technologies have emerged that allow you to run a powerful local GUI and connect it to an MCP server. They will work with Serena out of the box. Some of the leading open source GUI technologies offering this are Jan, OpenHands, OpenWebUI and Agno. They allow combining Serena with almost any LLM (including locally running ones) and offer various other integrations.
Serena combines tools for semantic code retrieval with editing capabilities and shell execution. Serena's behavior can be further customized through Modes and Contexts. Find the complete list of tools below.
The use of all tools is generally recommended, as this allows Serena to provide the most value: Only by executing shell commands (in particular, tests) can Serena identify and correct mistakes autonomously.
However, it should be noted that the execute_shell_command tool allows for arbitrary code execution.
When using Serena as an MCP Server, clients will typically ask the user for permission
before executing a tool, so as long as the user inspects execution parameters beforehand,
this should not be a problem.
However, if you have concerns, you can choose to disable certain commands in your project's
.yml configuration file.
If you only want to use Serena purely for analyzing code and suggesting implementations
without modifying the codebase, you can enable read-only mode by setting read_only: true in your project configuration file.
This will automatically disable all editing tools and prevent any modifications to your codebase while still
allowing all analysis and exploration capabilities.
In general, be sure to back up your work and use a version control system in order to avoid losing any work.
Serena's behavior and toolset can be adjusted using contexts and modes. These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in.
A context defines the general environment in which Serena is operating. It influences the initial system prompt and the set of available tools. A context is set at startup when launching Serena (e.g., via CLI options for an MCP server or in the agent script) and cannot be changed during an active session.
Serena comes with pre-defined contexts:
desktop-app: Tailored for use with desktop applications like Claude Desktop. This is the default.
agent: Designed for scenarios where Serena acts as a more autonomous agent, for example, when used with Agno.
ide-assistant: Optimized for integration into IDEs like VSCode, Cursor, or Cline, focusing on in-editor coding assistance.
Choose the context that best matches the type of integration you are using.
When launching Serena, specify the context using --context <context-name>.
Note that for cases where parameter lists are specified (e.g. Claude Desktop), you must add two parameters to the list.
If you are using a local server (such as Llama.cpp) which requires you to use OpenAI-compatible tool descriptions, use context oaicompat-agent instead of agent.
Modes further refine Serena's behavior for specific types of tasks or interaction styles. Multiple modes can be active simultaneously, allowing you to combine their effects. Modes influence the system prompt and can also alter the set of available tools by excluding certain ones.
Examples of built-in modes include:
planning: Focuses Serena on planning and analysis tasks.
editing: Optimizes Serena for direct code modification tasks.
interactive: Suitable for a conversational, back-and-forth interaction style.
one-shot: Configures Serena for tasks that should be completed in a single response, often used with planning for generating reports or initial plans.
no-onboarding: Skips the initial onboarding process if it's not needed for a particular session.
onboarding: (Usually triggered automatically) Focuses on the project onboarding process.
Modes can be set at startup (similar to contexts) but can also be switched dynamically during a session. You can instruct the LLM to use the switch_modes tool to activate a different set of modes (e.g., "switch to planning and one-shot modes").
When launching Serena, specify modes using --mode <mode-name>; multiple modes can be specified, e.g. --mode planning --mode no-onboarding.
:warning: Mode Compatibility: While you can combine modes, some may be semantically incompatible (e.g., interactive and one-shot). Serena currently does not prevent incompatible combinations; it is up to the user to choose sensible mode configurations.
You can create your own contexts and modes to precisely tailor Serena to your needs in two ways:
You can use Serena's CLI to manage modes and contexts. Check out
uvx --from git+https://github.com/oraios/serena serena mode --helpand
uvx --from git+https://github.com/oraios/serena serena context --help NOTE: Custom contexts/modes are simply YAML files in <home>/.serena, they are automatically registered and available for use by their name (filename without the .yml extension). If you don't want to use Serena's CLI, you can create and manage them in any way you see fit.
Using external YAML files: When starting Serena, you can also provide an absolute path to a custom .yml file for a context or mode.
This customization allows for deep integration and adaptation of Serena to specific project requirements or personal preferences.
By default, Serena will perform an onboarding process when it is started for the first time for a project. The goal of the onboarding is for Serena to get familiar with the project and to store memories, which it can then draw upon in future interactions. If an LLM should fail to complete the onboarding and does not actually write the respective memories to disk, you may need to ask it to do so explicitly.
The onboarding will usually read a lot of content from the project, thus filling up the context. It can therefore be advisable to switch to another conversation once the onboarding is complete. After the onboarding, we recommend that you have a quick look at the memories and, if necessary, edit them or add additional ones.
Memories are files stored in .serena/memories/ in the project directory,
which the agent can choose to read in subsequent interactions.
Feel free to read and adjust them as needed; you can also add new ones manually.
Every file in the .serena/memories/ directory is a memory file.
Whenever Serena starts working on a project, the list of memories is
provided, and the agent can decide to read them.
We found that memories can significantly improve the user experience with Serena.
Serena uses the code structure for finding, reading and editing code. This means that it will work well with well-structured code but may perform poorly on fully unstructured one (like a "God class" with enormous, non-modular functions). Furthermore, for languages that are not statically typed, type annotations are highly beneficial.
It is best to start a code generation task from a clean git state. Not only will
this make it easier for you to inspect the changes, but also the model itself will
have a chance of seeing what it has changed by calling git diff and thereby
correct itself or continue working in a followup conversation if needed.
:warning: Important: since Serena will write to files using the system-native line endings
and it might want to look at the git diff, it is important to
set git config core.autocrlf to true on Windows.
With git config core.autocrlf set to false on Windows, you may end up with huge diffs
only due to line endings. It is generally a good idea to globally enable this git setting on Windows:
git config --global core.autocrlf trueSerena can successfully complete tasks in an agent loop, where it iteratively acquires information, performs actions, and reflects on the results. However, Serena cannot use a debugger; it must rely on the results of program executions, linting results, and test results to assess the correctness of its actions. Therefore, software that is designed to meaningful interpretable outputs (e.g. log messages) and that has a good test coverage is much easier to work with for Serena.
We generally recommend to start an editing task from a state where all linting checks and tests pass.
We found that it is often a good idea to spend some time conceptualizing and planning a task before actually implementing it, especially for non-trivial task. This helps both in achieving better results and in increasing the feeling of control and staying in the loop. You can make a detailed plan in one session, where Serena may read a lot of your code to build up the context, and then continue with the implementation in another (potentially after creating suitable memories).
In our experience, LLMs are bad at counting, i.e. they have problems inserting blocks of code in the right place. Most editing operations can be performed at the symbolic level, allowing this problem is overcome. However, sometimes, line-level insertions are useful.
Serena is instructed to double-check the line numbers and any code blocks that it will edit, but you may find it useful to explicitly tell it how to edit code if you run into problems. We are working on making Serena's editing capabilities more robust.
For long and complicated tasks, or tasks where Serena has read a lot of content, you may come close to the limits of context tokens. In that case, it is often a good idea to continue in a new conversation. Serena has a dedicated tool to create a summary of the current state of the progress and all relevant info for continuing it. You can request to create this summary and write it to a memory. Then, in a new conversation, you can just ask Serena to read the memory and continue with the task. In our experience, this worked really well. On the up-side, since in a single session there is no summarization involved, Serena does not usually get lost (unlike some other agents that summarize under the hood), and it is also instructed to occasionally check whether it's on the right track.
Moreover, Serena is instructed to be frugal with context (e.g., to not read bodies of code symbols unnecessarily), but we found that Claude is not always very good in being frugal (Gemini seemed better at it). You can explicitly instruct it to not read the bodies if you know that it's not needed.
When using Serena through an MCP Client, you can use it together with other MCP servers. However, beware of tool name collisions! See info on that above.
Currently, there is a collision with the popular Filesystem MCP Server. Since Serena also provides filesystem operations, there is likely no need to ever enable these two simultaneously.
Serena provides two convenient ways of accessing the logs of the current session:
via the web-based dashboard (enabled by default)
This is supported on all platforms.
By default, it will be accessible at http://localhost:24282/dashboard/index.html,
but a higher port may be used if the default port is unavailable/multiple instances are running.
via the GUI tool (disabled by default)
This is mainly supported on Windows, but it may also work on Linux; macOS is unsupported.
Both can be enabled, configured or disabled in Serena's configuration file (serena_config.yml, see above).
If enabled, they will automatically be opened as soon as the Serena agent/MCP server is started.
The web dashboard will display usage statistics of Serena's tools if you set record_tool_usage_stats: True in your config.
In addition to viewing logs, both tools allow to shut down the Serena agent. This function is provided, because clients like Claude Desktop may fail to terminate the MCP server subprocess when they themselves are closed.
Support for MCP Servers in Claude Desktop and the various MCP Server SDKs are relatively new developments and may display instabilities.
The working configuration of an MCP server may vary from platform to platform and from client to client. We recommend always using absolute paths, as relative paths may be sources of errors. The language server is running in a separate sub-process and is called with asyncio – sometimes a client may make it crash. If you have Serena's log window enabled, and it disappears, you'll know what happened.
Some clients may not properly terminate MCP servers, look out for hanging python processes and terminate them manually, if needed.
To our knowledge, Serena is the first fully-featured coding agent where the entire functionality is available through an MCP server, thus not requiring API keys or subscriptions.
Many prominent subscription-based coding agents are parts of IDEs like Windsurf, Cursor and VSCode. Serena's functionality is similar to Cursor's Agent, Windsurf's Cascade or VSCode's agent mode.
Serena has the advantage of not requiring a subscription. A potential disadvantage is that it is not directly integrated into an IDE, so the inspection of newly written code is not as seamless.
More technical differences are:
Serena is not bound to a specific IDE or CLI. Serena's MCP server can be used with any MCP client (including some IDEs), and the Agno-based agent provides additional ways of applying its functionality.
Serena is not bound to a specific large language model or API.
Serena navigates and edits code using a language server, so it has a symbolic understanding of the code. IDE-based tools often use a RAG-based or purely text-based approach, which is often less powerful, especially for large codebases.
Serena is open-source and has a small codebase, so it can be easily extended and modified.
An alternative to subscription-based agents are API-based agents like Claude Code, Cline, Aider, Roo Code and others, where the usage costs map directly to the API costs of the underlying LLM. Some of them (like Cline) can even be included in IDEs as an extension. They are often very powerful and their main downside are the (potentially very high) API costs.
Serena itself can be used as an API-based agent (see the section on Agno above). We have not yet written a CLI tool or a dedicated IDE extension for Serena (and there is probably no need for the latter, as Serena can already be used with any IDE that supports MCP servers). If there is demand for a Serena as a CLI tool like Claude Code, we will consider writing one.
The main difference between Serena and other API-based agents is that Serena can also be used as an MCP server, thus not requiring an API key and bypassing the API costs. This is a unique feature of Serena.
There are other MCP servers designed for coding, like DesktopCommander and codemcp. However, to the best of our knowledge, none of them provide semantic code retrieval and editing tools; they rely purely on text-based analysis. It is the integration of language servers and the MCP that makes Serena unique and so powerful for challenging coding tasks, especially in the context of larger codebases.
We built Serena on top of multiple existing open-source technologies, the most important ones being:
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). Solid-LSP provides pure synchronous LSP calls and extends the original library with the symbolic logic that Serena required.
Agno and the associated agent-ui, which we use to allow Serena to work with any model, beyond the ones supporting the MCP.
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).
It is straightforward to extend Serena's AI functionality with your own ideas.
Simply implement a new tool by subclassing
serena.agent.Tool and implement the apply method with a signature
that matches the tool's requirements.
Once implemented, SerenaAgent will automatically have access to the new tool.
It is also relatively straightforward to add support for a new programming language.
We look forward to seeing what the community will come up with! For details on contributing, see contributing guidelines.
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 by name.
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_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.
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
Activates the project with the given name.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | The name of a registered project to activate or a path to a project directory. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing side effects, but it only says 'activates' without explaining what that entails. No information about state changes, errors, or requirements is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words, making it extremely easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is too sparse for the agent to understand the tool's role in the broader workflow. It lacks information about when to activate a project or what consequences this action has.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a full description of the parameter, covering both names and paths, so the description adds little and even narrows the meaning by saying 'given name' instead of 'name or path'. Baseline 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (activates) and the resource (project), making the primary purpose obvious. However, it does not explicitly differentiate from other tools and slightly narrows the parameter to 'name' even though the schema allows a path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives, nor are prerequisites or effects mentioned. The description only states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks whether project onboarding was already performed. You should always call this tool before beginning to actually work on the project/after activating a project, but after calling the initial instructions tool.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Checks' implies a read-only, non-mutating operation, and the sequencing context (call after activation, before work) adds behavioral insight. However, it does not explicitly state side effects (none expected) or what happens if onboarding is not performed, leaving some ambiguity. Still, for a simple status check, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, followed by concise usage context. Every sentence adds value, and there is no filler. The structure is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, simple status check tool with an output schema, the description is complete. It explains what it does and when to use it, and the output schema covers return values. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters, the baseline is 4 per the rubric. The description does not need to add parameter information since none exist. It correctly omits parameter details, and the schema coverage is 100% (vacuously).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks whether project onboarding was performed, using a specific verb ('Checks') and resource ('project onboarding'). It distinguishes from sibling tools like 'onboarding' which likely performs the onboarding, and the mention of sequencing clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: always call before working on the project, after activating a project, and after calling the initial instructions tool. This is clear and actionable, though it does not explicitly name alternatives, the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a new file or overwrite an existing file. Returns a message indicating success or failure.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The (utf-8-encoded) content to write to the file. | |
| relative_path | Yes | The relative path to the file to create. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the destructive nature of overwriting and the return message type ('Returns a message indicating success or failure'). However, it does not mention potential side effects like handling of missing directories or encoding behavior beyond the utf-8 note in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the verb and resource, and directly states the return value. Every word adds value and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with well-described schema and a stated return message, the description is complete enough. It could explicitly mention that overwriting replaces content without confirmation, but that is already implied by 'overwrite an existing file'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage for both parameters ('relative_path' and 'content'), so the tool description adds no additional parameter guidance beyond what the schema provides. The schema itself sufficiently documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Write' and identifies the resource as a file, clearly stating it creates or overwrites. This distinguishes it from siblings like find_file, read_file, and write_memory, which target different operations or storage types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating/overwriting text files (as indicated by the tool name) but does not explicitly mention when to prefer this tool over alternatives like write_memory or edit tools. There is no exclusion or alternative guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a memory file. Should only happen if a user asks for it explicitly, for example by saying that the information retrieved from a memory file is no longer correct or no longer relevant for the project.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_file_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does add a behavioral constraint (only on explicit user request), but it does not disclose the permanence of the deletion or any potential side effects. For a destructive operation, this is a notable absence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the first sentence providing the core action and the second adding usage guidance. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description lacks parameter semantics and does not address what happens if the memory file does not exist. The output schema may cover return values, but the input usage is not fully specified. Overall, it is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, memory_file_name, with no schema description (0% coverage). The tool description only mentions 'memory file' and does not specify the expected format, path, or any constraints for the parameter. It adds little beyond the parameter name itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool deletes a memory file, using a specific verb and resource. It distinguishes from sibling memory tools (write_memory, read_memory, list_memories) by focusing specifically on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states that deletion should only happen upon explicit user request, and provides concrete examples of such requests. This clearly delineates when to use the tool and guards against proactive deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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!. Returns a JSON object containing the command's stdout and optionally stderr output.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | The working directory to execute the command in. If None, the project root will be used. | |
| command | Yes | The shell command to execute. | |
| capture_stderr | No | Whether to capture and return stderr output. | |
| max_answer_chars | No | If the output is longer than this number of characters, no content will be returned. -1 means using the default value, don't adjust unless there is no other way to get the content required for the task. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return format (JSON with stdout and optionally stderr) and hints at memory-checking behavior. However, with no annotations, it leaves critical behavioral aspects undisclosed: shell execution can have arbitrary side effects (file modifications, system changes), and there's no mention of timeouts or error handling. The safety warning is advisory, not a transparency disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, starts with the primary purpose, and includes a necessary safety caution. The sentence about memory is slightly ambiguous but not wasteful. It avoids excessive detail, so it's well-structured for quick reading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool's complexity is high (arbitrary shell execution), and while the output schema and parameter schema cover return values and parameters, the description doesn't explain execution context, side effects, or safety mechanisms beyond the rm example. It also doesn't discuss timeouts or exit code behavior. Given the available annotations are absent, the description only partially covers what an agent needs to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter descriptions, so the baseline is 3. The description adds minimal parameter information beyond the schema, only linking 'optionally stderr output' to capture_stderr. It doesn't elaborate on cwd or max_answer_chars behavior, which the schema already covers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a shell command and return its output,' which is a specific verb+resource. It is distinct from sibling tools (file operations, memory operations) as the only tool for shell execution. The mention of returning stdout/stderr clarifies the output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a prerequisite ('If there is a memory about suggested commands, read that first') and an explicit safety exclusion ('Never execute unsafe shell commands like rm -rf / or similar!'). However, it doesn't name alternatives or explain when this tool should be preferred over file-specific tools, so it lacks explicit when-not/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds non-gitignored files matching the given file mask within the given relative path. Returns a JSON object with the list of matching files.
| Name | Required | Description | Default |
|---|---|---|---|
| file_mask | Yes | The filename or file mask (using the wildcards * or ?) to search for. | |
| relative_path | Yes | The relative path to the directory to search in; pass "." to scan the project root. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the key behavioral trait that it ignores gitignored files, and it states the return format. However, it does not disclose whether the search is recursive, what form the paths take in the result, or any potential side effects. Since annotations are absent, the description carries the full burden but leaves these behavioral aspects unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and contains no filler. It conveys the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and full schema parameter coverage, the description covers the essentials. The only notable gap is the lack of clarity about recursion depth and whether the returned paths are absolute or relative, but overall it's a well-specified tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides clear descriptions for both file_mask and relative_path, with 100% coverage. The description does not add any further detail about parameter formats, examples, or constraints, so it adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: finds files by mask, with the specific scope of non-gitignored files and a relative path. It also specifies the return type (JSON object with list), and the verb 'Finds' is appropriate. This distinguishes it from sibling tools like read_file (content reading) and search_for_pattern (presumably content search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to locate files by name pattern) but does not explicitly mention alternatives or exclusions. Sibling tools like list_dir and search_for_pattern are not referenced, so the agent must infer the appropriate tool without clear guidance on when to prefer this over those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Returns a list of JSON objects with the symbols referencing the requested symbol.
| Name | Required | Description | Default |
|---|---|---|---|
| name_path | Yes | For finding the symbol to find references for, same logic as in the `find_symbol` tool. | |
| exclude_kinds | No | Same as in the `find_symbol` tool. | |
| include_kinds | No | Same as in the `find_symbol` tool. | |
| relative_path | Yes | The relative path to the file containing the symbol for which to find references. Note that here you can't pass a directory but must pass a file. | |
| max_answer_chars | No | Same as in the `find_symbol` tool. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the return format (list of JSON objects with metadata and code snippets) but does not explicitly state that the tool is read-only or mention error conditions, permissions, or performance implications. The verb 'finds' implies non-mutating behavior, but this is implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every clause adds value. It is concise without sacrificing essential information about what the tool does and what it returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and fully described parameters, the description sufficiently covers the tool's core function and return format. It lacks explicit usage scenarios and exclusions, but for a well-schema'd symbol-reference tool, it is adequately complete for an agent to select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a descriptive comment referencing find_symbol where applicable. The tool description itself adds no further parameter-level detail, which is acceptable given the schema's completeness. Cross-references to find_symbol provide contextual meaning but are embedded in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: finding references to a symbol at a given name_path. It specifies the output includes metadata and code snippets, distinguishing it from sibling tools like find_symbol (which finds definitions) or search_for_pattern (which searches text patterns).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use the tool (when you need to find references to a symbol), but it does not explicitly state when not to use it or mention alternative tools. Repeated references to find_symbol's parameter logic provide some context but no direct decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves information on all symbols/code entities (classes, methods, etc.) based on the given name_path,
which represents a pattern for the symbol's path within the symbol tree of a single file.
The returned symbol location can be used for edits or further queries.
Specify depth > 0 to retrieve children (e.g., methods of a class).
The matching behavior is determined by the structure of name_path, which can
either be a simple name (e.g. "method") or a name path like "class/method" (relative name path)
or "/class/method" (absolute name path). Note that the name path is not a path in the file system
but rather a path in the symbol tree within a single file. Thus, file or directory names should never
be included in the name_path. For restricting the search to a single file or directory,
the within_relative_path parameter should be used instead. The retrieved symbols' name_path attribute
will always be composed of symbol names, never file or directory names.
Key aspects of the name path matching behavior:
Trailing slashes in name_path play no role and are ignored.
The name of the retrieved symbols will match (either exactly or as a substring)
the last segment of name_path, while other segments will restrict the search to symbols that
have a desired sequence of ancestors.
If there is no starting or intermediate slash in name_path, there is no
restriction on the ancestor symbols. For example, passing method will match
against symbols with name paths like method, class/method, class/nested_class/method, etc.
If name_path contains a / but doesn't start with a /, the matching is restricted to symbols
with the same ancestors as the last segment of name_path. For example, passing class/method will match against
class/method as well as nested_class/class/method but not method.
If name_path starts with a /, it will be treated as an absolute name path pattern, meaning
that the first segment of it must match the first segment of the symbol's name path.
For example, passing /class will match only against top-level symbols like class but not against nested_class/class.
Passing /class/method will match against class/method but not nested_class/class/method or method. Returns a list of symbols (with locations) matching the name.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Depth to retrieve descendants (e.g., 1 for class methods/attributes). | |
| name_path | Yes | The name path pattern to search for, see above for details. | |
| include_body | No | If True, include the symbol's source code. Use judiciously. | |
| exclude_kinds | No | Optional. List of LSP symbol kind integers to exclude. Takes precedence over `include_kinds`. If not provided, no kinds are excluded. | |
| include_kinds | No | Optional. List of LSP symbol kind integers to include. (e.g., 5 for Class, 12 for Function). Valid kinds: 1=file, 2=module, 3=namespace, 4=package, 5=class, 6=method, 7=property, 8=field, 9=constructor, 10=enum, 11=interface, 12=function, 13=variable, 14=constant, 15=string, 16=number, 17=boolean, 18=array, 19=object, 20=key, 21=null, 22=enum member, 23=struct, 24=event, 25=operator, 26=type parameter. If not provided, all kinds are included. | |
| relative_path | No | Optional. Restrict search to this file or directory. If None, searches entire codebase. If a directory is passed, the search will be restricted to the files in that directory. If a file is passed, the search will be restricted to that file. If you have some knowledge about the codebase, you should use this parameter, as it will significantly speed up the search as well as reduce the number of results. | |
| max_answer_chars | No | Max characters for the JSON result. If exceeded, no content is returned. -1 means the default value from the config will be used. | |
| substring_matching | No | If True, use substring matching for the last segment of `name`. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description offers detailed matching semantics (absolute vs relative paths, trailing slashes, ancestor constraints) but has no annotations to lean on. It contains an ambiguous statement about exact vs substring matching, and does not explain how the substring_matching parameter modifies behavior. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a main paragraph and bullet list, but it is quite long and includes some redundant details and an erroneous parameter name. While the complexity of name_path justifies length, the inaccurate reference makes it less concise and clear than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, the description focuses almost exclusively on name_path and relative_path, leaving out integrated guidance on include_kinds, exclude_kinds, include_body, and substring_matching. For a tool with eight parameters, this is a notable gap, but the schema partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% parameter coverage. The description adds significant value for name_path, but incorrectly references a non-existent parameter (`within_relative_path`) and does not clarify how substring_matching interacts with the described rules. This reduces reliability of the added guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves information on code entities using a name_path pattern, with specific examples and distinctions from file paths. It clearly identifies the resource (symbols) and the operation (retrieve), differentiating it from sibling tools like find_file and find_referencing_symbols.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides useful guidance on when to use depth and relative_path, but misnames the parameter as `within_relative_path` instead of `relative_path`, which could mislead an agent. It does not explicitly compare this tool to alternatives like find_referencing_symbols or get_symbols_overview, leaving the when-not-to-use unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Returns a JSON object containing info about top-level symbols in the file.
| Name | Required | Description | Default |
|---|---|---|---|
| relative_path | Yes | The relative path to the file to get the overview of. | |
| max_answer_chars | No | If the overview is longer than this number of characters, no content will be returned. -1 means the default value from the config will be used. Don't adjust unless there is really no other way to get the content required for the task. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns a JSON object with top-level symbols, which is a useful behavioral detail. However, it does not explicitly state that the tool is read-only or describe any potential side effects or limitations beyond the parameter schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, followed by usage guidance and return value. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple tool with 2 parameters and an output schema, the description is complete. It explains the tool's role, when to use it, and what it returns. The slight gap is that it does not explicitly mention exclusion criteria or contrast with other tools, but overall it provides sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning about the parameters beyond what the schema already provides, but the schema fully documents relative_path and max_answer_chars, so no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'get a high-level understanding of the code symbols in a file' and specifies the return of a JSON object with top-level symbols. This distinguishes it from sibling tools like find_symbol or read_file, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: '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.' This gives clear context for when to use it, though it does not name specific alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inserts the given body/content after the end 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.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The body/content to be inserted. The inserted code shall begin with the next line after the symbol. | |
| name_path | Yes | Name path of the symbol after which to insert content (definitions in the `find_symbol` tool apply). | |
| relative_path | Yes | The relative path to the file containing the symbol. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses a key behavioral detail: 'The inserted code shall begin with the next line after the symbol' and 'via the symbol's location.' However, it does not cover error handling or prerequisites (e.g., symbol must exist), leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and followed by a typical use case. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a code insertion tool with an output schema and fully described parameters, the description provides adequate context: it specifies the insertion point relative to the symbol definition and gives use cases. It does not mention error scenarios or relation to sibling insert_before_symbol, but these are not critical given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The tool description itself adds minimal parameter semantics beyond the schema; the only extra context is the cross-reference in the schema to find_symbol definitions, which is not in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Inserts' and identifies the resource: 'body/content after the end of the definition of the given symbol.' It distinguishes from siblings like insert_before_symbol by specifying 'after' and clarifies typical use cases (class, function, method, field, or variable assignment).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case scenario: 'insert a new class, function, method, field or variable assignment.' However, it does not explicitly mention alternatives or when not to use it, though the context of symbol locations implies coordination with find_symbol.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The body/content to be inserted before the line in which the referenced symbol is defined. | |
| name_path | Yes | Name path of the symbol before which to insert content (definitions in the `find_symbol` tool apply). | |
| relative_path | Yes | The relative path to the file containing the symbol. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates a mutation (inserts content) but does not explain side effects, such as how existing content is shifted, whether the symbol must exist, error behavior, or any permissions required. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. It front-loads the core action and then gives a concrete example of usage. Every word earns its place, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with 3 required parameters and no annotations. The description explains the core use case well, but it omits important behavioral details such as prerequisites (e.g., file and symbol must exist) and potential impacts on surrounding code. The presence of an output schema reduces the need to describe return values, but the behavioral gaps leave the description incomplete for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already described in the schema. The description adds little over the schema—it refers to 'given content' and 'given symbol' but does not elaborate on the specific semantics of `name_path`, `relative_path`, or `body` beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Inserts the given content before the beginning of the definition of the given symbol.' It uses a specific verb and resource, and the placement 'before' distinguishes it from the sibling tool `insert_after_symbol`. Typical use cases are also listed, reinforcing purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (e.g., inserting a class, function, or import statement before a symbol). However, it does not explicitly mention when not to use it or point to alternatives like `insert_after_symbol` or `replace_symbol_body`. The usage context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all non-gitignored files and directories in the given directory (optionally with recursion). Returns a JSON object with the names of directories and files within the given directory.
| Name | Required | Description | Default |
|---|---|---|---|
| recursive | Yes | Whether to scan subdirectories recursively. | |
| relative_path | Yes | The relative path to the directory to list; pass "." to scan the project root. | |
| max_answer_chars | No | If the output is longer than this number of characters, no content will be returned. -1 means the default value from the config will be used. Don't adjust unless there is really no other way to get the content required for the task. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behavioral traits: the non-gitignored filtering, optional recursion, and JSON return format. This is sufficient for a simple read-only listing tool, though it could have been even more explicit about hidden files or symlink handling. The core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and contains no filler. Every word adds value, defining the tool's scope, behavior, and return format concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the presence of an output schema, and full parameter coverage, the description is largely complete. It covers the main purpose, filtering behavior, recursion option, and return type. It could have added a note about usage versus sibling tools or hidden files, but for a straightforward listing tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so parameters are already well-documented. The description adds minimal extra meaning—it confirms the directory target and recursion option but does not go beyond what the schema already states. Baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all non-gitignored files and directories in a given directory, with optional recursion. This specific verb+resource combination distinguishes it from sibling tools like find_file (search) and read_file (read contents). The return type (JSON object) is also specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: to enumerate directory contents, including the ability to recurse. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it over searching or reading files. No exclusions are mentioned, but it earns a 4 for clear context without explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available memories. Any memory can be read using the read_memory tool.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. The verb 'list' strongly implies a read-only, non-destructive operation, and the reference to read_memory clarifies that list returns memory references rather than content. It could mention scope or return format, but the basic behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary function, and the second sentence adds useful complementary guidance without redundancy or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless enumeration tool, the description sufficiently covers the purpose and the logical next step (reading a chosen memory). The presence of an output schema handles return details, so no further explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description adds no parameter-specific information, which is appropriate. Per the rubric, the baseline for 0 params is 4; the description doesn't mislead or omit anything about inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('list') and resource ('memories'). It distinguishes itself from siblings like read_memory by explicitly indicating that read_memory is for reading the content of a memory, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by saying 'Any memory can be read using the read_memory tool,' implying list_memories is for discovery/enumeration and read_memory is for retrieving content. It doesn't explicitly state when not to use it, but the complementary reference gives enough guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this tool if onboarding was not performed yet. You will call this tool at most once per conversation. Returns instructions on how to create the onboarding information.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool returns instructions and imposes a one-time-per-conversation limit, implying a read-only, side-effect-free operation. This is sufficient for a simple tool, though it could have explicitly stated non-modifying behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the key usage condition, and includes a critical behavioral constraint. Every word earns its place, with no redundancy or irrelevant detail. It is exceptionally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete: it states when to call, the constraint, and what it returns. No additional context is needed for the agent to invoke this tool correctly. The output schema covers return value details, so the description need not elaborate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (vacuously). The description does not need to explain parameters, and the baseline for zero-parameter tools is 4. The description adds no parameter-specific details, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to be called when onboarding has not been performed, and it returns instructions. It uses a specific condition ('if onboarding was not performed yet') and a clear resource ('instructions on how to create the onboarding information'). However, it does not explicitly differentiate from the sibling tool 'check_onboarding_performed', which likely serves a related but distinct function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear condition for usage ('if onboarding was not performed yet') and an explicit constraint ('at most once per conversation'). It does not mention any alternative tools or explicitly instruct the agent to first verify onboarding status with a sibling tool, which slightly limits guidance, but the condition itself is a strong usage indicator.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Instructions for preparing for a new conversation. This tool should only be called on explicit user request.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden on behavioral disclosure, but it reveals nothing about side effects, state changes, or what 'preparing' involves. The agent cannot infer whether this resets context, clears memory, or performs other actions, making it highly opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and the second sentence is directly useful. However, the first sentence essentially duplicates the tool name without adding new information, so not every sentence earns its keep; it is concise but somewhat wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low in complexity (no parameters) and has an output schema, so return value details may not be needed. However, the description omits crucial behavioral context—what 'preparing' does to the conversation state—leaving a significant gap in understanding when and why it should be invoked.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the description adds no conflicting or confusing parameter information. Per guidance, 0 params baseline is 4; the description aligns with the schema and adds no further need for documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Instructions for preparing for a new conversation' largely restates the tool name without specifying what the tool actually does. It lacks a concrete verb revealing the action or effect, and does not distinguish from siblings beyond a general 'preparing' notion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'This tool should only be called on explicit user request,' providing a clear when-to-use condition and an implicit exclusion (do not call automatically). It does not mention alternatives, but the condition is direct and useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Returns the full text of the file at the given relative path.
| Name | Required | Description | Default |
|---|---|---|---|
| end_line | No | The 0-based index of the last line to be retrieved (inclusive). If None, read until the end of the file. | |
| start_line | No | The 0-based index of the first line to be retrieved. | |
| relative_path | Yes | The relative path to the file to read. | |
| max_answer_chars | No | If the file (chunk) 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It communicates the core read operation and return text, but does not mention the max_answer_chars behavior where oversized chunks produce no content, nor line-range edge cases. The schema covers these details, so the description is minimally viable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loads the main purpose, then provides usage guidance, then states the return value. Every clause earns its place and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, high schema coverage, and presence of an output schema, the description is largely sufficient. It explains purpose, use cases, and return behavior, though a brief mention of the max_answer_chars truncation rule would make it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it hints at chunking via 'or a chunk of it' but does not explain start_line/end_line semantics or max_answer_chars beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Reads the given file or a chunk of it.' It further distinguishes itself from sibling symbol-oriented tools by advising find_symbol/find_referencing_symbols for symbol lookup, making the purpose clear and unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when symbolic operations should be preferred instead of read_file, giving named alternatives. This provides actionable guidance on when not to use the tool, satisfying the usage guidelines dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the content of a memory file. This tool should only be used if the information is relevant to the current task. You can infer whether the information is relevant from the memory file name. You should not read the same memory file multiple times in the same conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| max_answer_chars | No | ||
| memory_file_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about relevance and avoiding repeated reads, but does not describe return format, error behavior, or side effects. The read-only nature is implied by the verb 'Read', but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences. The first sentence front-loads the core purpose, and the subsequent sentences provide essential usage guidance without any filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with an output schema available, the description covers the essential purpose and usage context. It lacks details about parameter semantics (e.g., max_answer_chars) and potential error conditions, but these are partially addressed by the schema and output schema. Overall, it is sufficiently complete for a basic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter explanations. It does not mention max_answer_chars at all, and only indirectly references memory_file_name through the phrase 'memory file name'. The schema already provides titles, but the description adds no additional meaning to the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Read the content of a memory file', clearly identifying the action and resource. It distinguishes from sibling tools like read_file by specifying 'memory file', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('only be used if the information is relevant to the current task') and a when-not-to rule ('You should not read the same memory file multiple times in the same conversation'). However, it does not name alternative tools, so it misses the 'alternatives' part of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces one or more occurrences of the given regular expression. This is the preferred way to replace content in a file whenever the symbol-level tools are not appropriate. Even large sections of code can be replaced by providing a concise regular expression of the form "beginning.*?end-of-text-to-be-replaced". Always try to use wildcards to avoid specifying the exact content of the code to be replaced, especially if it spans several lines.
IMPORTANT: REMEMBER TO USE WILDCARDS WHEN APPROPRIATE! I WILL BE VERY UNHAPPY IF YOU WRITE LONG REGEXES WITHOUT USING WILDCARDS INSTEAD!.
| Name | Required | Description | Default |
|---|---|---|---|
| repl | Yes | The string to replace the matched content with, which may contain backreferences like \1, \2, etc. Make sure to escape special characters appropriately, e.g., use `\\n` for a literal `\n`. | |
| regex | Yes | A Python-style regular expression, matches of which will be replaced. Dot matches all characters, multi-line matching is enabled. | |
| relative_path | Yes | The relative path to the file. | |
| allow_multiple_occurrences | No | If True, the regex may match multiple occurrences in the file and all of them will be replaced. If this is set to False and the regex matches multiple occurrences, an error will be returned (and you may retry with a revised, more specific regex). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the core replacement behavior and wildcard strategy, but it does not warn that this is a permanent file mutation, does not mention permission or irreversibility risks, and does not explain error behavior for multiple matches (though that is in the schema). For a mutation tool with no annotation safety hints, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise: two sentences of guidance plus an emphasized note. However, the all-caps wildcard warning is somewhat redundant because the same advice appears in the preceding sentence. The structure front-loads the core purpose and usage guidance well, but the emphatic note could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, an output schema, and no annotations, the description offers useful usage strategy but omits critical context for a mutation tool: no warning about permanent changes, no mention of failure modes (e.g., multiple-match error when allow_multiple_occurrences is false), and no explicit pointer to sibling tools for simpler replacements. It is not fully complete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing a strong baseline. The description adds meaningful guidance for the 'regex' parameter by suggesting wildcard usage and a compact form 'beginning.*?end-of-text-to-be-replaced,' which helps agents construct effective patterns. It does not add information for 'repl' or 'allow_multiple_occurrences,' but the schema already covers those well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Replaces one or more occurrences of the given regular expression.' It clearly distinguishes itself from sibling symbol-level tools by stating it is 'the preferred way... whenever the symbol-level tools are not appropriate.' This makes the tool's purpose unambiguous and differentiates it from replace_symbol_body and similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it: 'preferred way to replace content in a file whenever the symbol-level tools are not appropriate.' It also provides concrete guidance on using wildcards and regex forms like 'beginning.*?end-of-text-to-be-replaced.' However, it does not explicitly name specific alternative tools or state clear when-not-to-use conditions beyond the broad 'symbol-level tools not appropriate' phrase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces the body of the symbol with the given name_path.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The new symbol body. Important: Begin directly with the symbol definition and provide no leading indentation for the first line (but do indent the rest of the body according to the context). | |
| name_path | Yes | For finding the symbol to replace, same logic as in the `find_symbol` tool. | |
| relative_path | Yes | The relative path to the file containing the symbol. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It states 'replaces' (a mutation), but provides no disclosure about irreversibility, whether the symbol must exist, or any side effects. It does not mention that the body must be indented correctly (though the schema covers that). This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and relatively concise. However, the phrasing is awkward and could be clearer (e.g., 'Replaces the body of the symbol identified by `name_path` with the provided `body`'). It earns its place but not exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and only a terse description. It lacks essential context about how name_path relates to find_symbol (though schema mentions it), what happens if the symbol is not found, and whether the operation is reversible. The output schema exists but does not compensate for these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented. The description adds nothing beyond what the schema provides, including the meaning of name_path and body. Baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Replaces') and identifies the resource ('body of the symbol') with a lookup mechanism ('name_path'). It distinguishes from sibling tools like insert_before_symbol/insert_after_symbol (which insert) and replace_regex (which replaces via regex). The phrase 'with the given `name_path`' is slightly ambiguous but contextually implies the symbol identified by name_path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention cases where replace_regex or insert_* would be more appropriate, nor any prerequisites like needing to find_symbol first. The intended usage is only implied by the tool's name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Offers a flexible search for arbitrary patterns in the codebase, including the possibility to search in non-code files. Generally, symbolic operations like find_symbol or find_referencing_symbols should be preferred if you know which symbols you are looking for.
Pattern Matching Logic: For each match, the returned result will contain the full lines where the substring pattern is found, as well as optionally some lines before and after it. The pattern will be compiled with DOTALL, meaning that the dot will match all characters including newlines. This also means that it never makes sense to have .* at the beginning or end of the pattern, but it may make sense to have it in the middle for complex patterns. If a pattern matches multiple lines, all those lines will be part of the match. Be careful to not use greedy quantifiers unnecessarily, it is usually better to use non-greedy quantifiers like .*? to avoid matching too much content.
File Selection Logic:
The files in which the search is performed can be restricted very flexibly.
Using restrict_search_to_code_files is useful if you are only interested in code symbols (i.e., those
symbols that can be manipulated with symbolic tools like find_symbol).
You can also restrict the search to a specific file or directory,
and provide glob patterns to include or exclude certain files on top of that.
The globs are matched against relative file paths from the project root (not to the relative_path parameter that
is used to further restrict the search).
Smartly combining the various restrictions allows you to perform very targeted searches. Returns A mapping of file paths to lists of matched consecutive lines.
| Name | Required | Description | Default |
|---|---|---|---|
| relative_path | No | Only subpaths of this path (relative to the repo root) will be analyzed. If a path to a single file is passed, only that will be searched. The path must exist, otherwise a `FileNotFoundError` is raised. | |
| max_answer_chars | No | If the output is longer than this number of characters, no content will be returned. -1 means the default value from the config will be used. Don't adjust unless there is really no other way to get the content required for the task. Instead, if the output is too long, you should make a stricter query. | |
| substring_pattern | Yes | Regular expression for a substring pattern to search for. | |
| paths_exclude_glob | No | Optional glob pattern specifying files to exclude from the search. Matches against relative file paths from the project root (e.g., "*test*", "**/*_generated.py"). Takes precedence over paths_include_glob. Only matches files, not directories. If left empty, no files are excluded. | |
| paths_include_glob | No | Optional glob pattern specifying files to include in the search. Matches against relative file paths from the project root (e.g., "*.py", "src/**/*.ts"). Only matches files, not directories. If left empty, all non-ignored files will be included. | |
| context_lines_after | No | Number of lines of context to include after each match. | |
| context_lines_before | No | Number of lines of context to include before each match. | |
| restrict_search_to_code_files | No | Whether to restrict the search to only those files where analyzed code symbols can be found. Otherwise, will search all non-ignored files. Set this to True if your search is only meant to discover code that can be manipulated with symbolic tools. 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly by disclosing DOTALL compilation, greedy/non-greedy quantifier advice, multi-line matching behavior, line-based return content, and file selection semantics including glob matching relative to project root. It also clarifies the return mapping at the end.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but tightly structured with clear sections for pattern matching logic and file selection logic. Each paragraph adds necessary operational detail without fluff, and key guidance is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 8 parameters, no annotations, and an output schema, the description covers the essential usage, edge cases, performance pitfalls (greedy quantifiers), and file filtering nuances. It adequately explains how to restrict searches and what is returned, making it sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the pattern matching implications of substring_pattern (e.g., DOTALL, leading/trailing .* being useless) and clarifying how relative_path and globs interact, which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool offers 'flexible search for arbitrary patterns in the codebase' including non-code files, which is a specific verb+resource. It also distinguishes from siblings by explicitly recommending find_symbol or find_referencing_symbols when known symbols are sought.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says that symbolic operations like find_symbol or find_referencing_symbols should be preferred when symbols are known, providing an alternative usage path. It also gives guidance on when to use restrict_search_to_code_files and how to combine file selection restrictions for targeted searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Activates the desired modes, like ["editing", "interactive"] or ["planning", "one-shot"].
| Name | Required | Description | Default |
|---|---|---|---|
| modes | Yes | The names of the modes to activate. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states that it 'activates' modes but does not disclose behavioral traits such as whether it replaces current modes, affects conversation state, or has side effects. The examples help but do not convey the impact on the agent's state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, short and front-loaded with the action 'Activates'. The examples are useful and do not waste space. It earns its place with minimal verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter and full schema coverage, the description is fairly complete. However, since there is no annotation and the tool seems to affect mode state, additional context about expected mode names or effects would improve completeness. The output schema exists but is not shown; if it explains return values, the description need not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the only parameter 'modes', so the schema already explains it. The description adds context by showing example values ('editing', 'interactive', etc.), which enriches the parameter understanding beyond the generic schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Activates the desired modes') with specific resource ('modes') and examples ('editing', 'interactive', 'planning', 'one-shot'). While it doesn't explicitly compare with sibling tools, the verb 'activates' and mode names distinguish it from file/search/memory tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples of when to use it (activating modes like editing/interactive or planning/one-shot), which implies its context. However, it does not explicitly state when not to use it or mention alternative tools, which is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Think about the collected information and whether it is sufficient and relevant. This tool should ALWAYS be called after you have completed a non-trivial sequence of searching steps like find_symbol, find_referencing_symbols, search_files_for_pattern, read_file, etc.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior, but it only describes the thinking action itself. It does not state whether the tool has side effects, what it returns, or how the assessment should influence subsequent actions. This is partially mitigated by the simplicity of a no-op cognitive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and the usage guidance is concise with concrete examples. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an output schema, and a simple cognitive purpose, the description is sufficiently complete. It explains the trigger condition and the evaluation criteria, making the tool usable in a workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description accurately conveys that the tool acts on already-collected information, adding context beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to assess whether collected information is sufficient and relevant. It distinguishes itself from sibling thinking tools by focusing on 'collected information' rather than task adherence or completion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to call this tool: ALWAYS after a non-trivial sequence of search steps. However, it does not mention when not to use it or name alternative tools for similar reflection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Think about the task at hand and whether you are still on track. Especially important if the conversation has been going on for a while and there has been a lot of back and forth.
This tool should ALWAYS be called before you insert, replace, or delete code.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It indicates this is a cognitive check, but it does not explicitly state whether it has side effects, what happens when called, or why the "always before code" rule matters. It is not misleading, but it under-specifies behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three sentences, front-loads the primary purpose, and then adds a clear usage condition and a specific rule. Every sentence contributes necessary information with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool with an output schema, the description covers purpose, timing, and a firm usage rule. It does not mention alternatives or explicitly say it is side-effect free, but the tool's simplicity and the presence of an output schema lower the burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema description coverage is vacuously 100%, so there is nothing for the description to add about parameters. The baseline of 4 for parameterless tools applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: "Think about the task at hand and whether you are still on track." It distinguishes itself from sibling thinking tools by tying the usage to a concrete action: "always be called before you insert, replace, or delete code."
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong contextual usage guidance: "Especially important if the conversation has been going on for a while" and a firm rule: "should ALWAYS be called before you insert, replace, or delete code." It does not explicitly mention alternatives or when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whenever you feel that you are done with what the user has asked for, it is important to call this tool.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It merely instructs to call the tool, with no explanation of what happens when called, whether it is read-only, what output it produces, or any side effects. This is a critical gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is under-specified. It is not overly verbose, but the lack of informative content makes it borderline under-specification rather than efficient conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 params) and the existence of an output schema, the description still fails to explain the tool's purpose, behavioral effects, or expected output. It leaves the agent without sufficient context to understand why this tool is important or what it does beyond its name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so the baseline for 0 params is 4. The description adds nothing about parameters, which is acceptable since there are none to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states when to call the tool ('whenever you feel that you are done'), but does not explicitly state what the tool does beyond its name. It conveys the general purpose of self-checking completion, but is vague and does not distinguish clearly from sibling think_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear when-to-use condition ('when you feel done'), which is directly actionable. However, it does not mention when not to use it or list alternative tools, falling short of the full 5-point standard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| memory_name | Yes | ||
| max_answer_chars | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It mentions writing to memory in md format but does not disclose important behaviors such as whether existing memories are overwritten, whether memory names must be unique, or any potential side effects. The mutation implied by 'Write' is not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action ('Write some information'), and each clause adds relevant information (project usefulness, md format, meaningful name). It is slightly run-on but remains concise and free of unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema, so return values need not be explained. However, with no annotations and low schema coverage, the description should address overwrite behavior, naming constraints, and parameter meanings. It currently leaves significant gaps, making it incomplete for a write/mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (content, memory_name, max_answer_chars) with 0% description coverage. The description only indirectly hints at memory_name and content, and the phrase 'memory name should be meaningful' adds some semantic value. However, the max_answer_chars parameter is completely unexplained, and the description does not provide sufficient detail to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: writing project information to a memory in md format for future use. It explicitly mentions the format ('md format') and the need for a meaningful name, which distinguishes it from related memory tools like read_memory, delete_memory, and list_memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by saying 'that can be useful for future tasks', providing a clear reason to use this tool. However, it does not explicitly state when to use it over alternatives (e.g., when to use write_memory vs create_text_file) or provide any exclusions or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.4activate_projectcheck_onboarding_performedcreate_text_filedelete_memoryexecute_shell_commandfind_filefind_referencing_symbolsfind_symbolget_symbols_overviewinsert_after_symbolinsert_before_symbollist_dirlist_memoriesonboardingprepare_for_new_conversationread_fileread_memoryreplace_regexreplace_symbol_bodysearch_for_patternswitch_modesthink_about_collected_informationthink_about_task_adherencethink_about_whether_you_are_donewrite_memoryMost tools have clearly distinct purposes, such as find_file vs list_dir vs search_for_pattern. However, replace_regex and replace_symbol_body both modify file content, and the three think_about_* tools could be confused, though descriptions do differentiate them.
The vast majority use a consistent snake_case verb_noun pattern (e.g., find_file, read_file, write_memory). Minor deviations like 'onboarding' (noun) and 'check_onboarding_performed' (phrase) slightly break the pattern but remain readable.
With 25 tools, the server straddles the upper boundary of what is reasonable for its scope. The feature set is broad, covering file, symbol, memory, project, and meta operations, but the count feels heavy and could overwhelm an agent.
The server covers file read/create/edit/search, symbol analysis/editing, memory CRUD, and project onboarding, but lacks a dedicated file deletion tool (only delete_memory exists). Rename/move operations are also absent, which agents may need for full file lifecycle management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Project memory, semantic code search, and grounded agent context.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Raheem-19/serena-optimized'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
