Provides tools for code navigation in Neovim using LSP and Treesitter, allowing AI agents to get symbols, diagnostics, references, definitions, and manage the quickfix list.
Click on "Deploy 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., "@neovim-mcp find all references to the 'login' function and save to quickfix"
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.
Make your AI agent leverage Neovim for code navigation.
This MCP server allows you to access your Neovim instance so that your AI agent can:
use LSP functionalities: go to definition, find references, find symbols etc.
use Treesitter to inspect the AST (abstract syntaxt tree)
read and write to your quickfix list
This is my typical workflow:
open the project in Neovim
instruct the agent to e.g. find the flow of a feature in the codebase
the agent uses builtin bash tools (e.g. grep and find) as well as tools from this MCP to navigate the code
the agent returns a summary of the feature and saves the result locations to the Neovim quickfix list, with details for each location
a Neovim installation with LSP servers and treesitter
tested with Neovim 0.11. Older versions might work but they it's not guaranteed.
Node.js to run the MCP server
Related MCP server: lsp-mcp-server
The MCP server talks to Neovim over a unix socket at /tmp/nvim.
You must use the --listen option when starting Neovim. You have a couple of options:
directly from the terminal when invoking the program: nvim --listen /tmp/nvim
attach the instance to the socket at startup from your Neovim config:
-- init.lua
vim.fn.serverstart("/tmp/nvim")If you run multiple Neovim instances, add a toggle keymap — it lets you change which instance the MCP server talks to:
-- keymaps.lua
vim.keymap.set("n", "<leader>ts", function()
if vim.tbl_contains(vim.fn.serverlist(), "/tmp/nvim") then
vim.fn.serverstop("/tmp/nvim")
vim.notify("MCP server released")
else
os.remove("/tmp/nvim")
vim.fn.serverstart("/tmp/nvim")
vim.notify("MCP server assigned to this instance")
end
end, { desc = "[T]oggle MCP [S]erver to this instance" })This server is so simple that downloading a release is not worth it. You can just clone this repo and build the JS files with the following:
npm install && npm run buildDepending on your agent harness of choice this step might look different:
for Claude Code:
claude mcp add --transport stdio --scope user neovim-nav -- node /path/to/neovim-mcp/build/index.jsfor other clients (Cursor, etc.): add this to your MCP config file
{
"neovim-nav": {
"type": "stdio",
"command": "node",
"args": ["/path/to/neovim-mcp/build/index.js"]
}
}The server connects to /tmp/nvim by default. To use a different socket path specify the env variable NVIM_SOCKET_PATH:
Claude code:
claude mcp add --transport stdio --scope user neovim-nav -e NVIM_SOCKET_PATH=/tmp/my-nvim -- node /path/to/neovim-mcp/build/index.jsother clients:
{
"neovim-nav": {
"type": "stdio",
"command": "node",
"args": ["/path/to/neovim-mcp/build/index.js"],
"env": { "NVIM_SOCKET_PATH": "/tmp/custom-nvim-socket" }
}
}Remember to connect both your server and Neovim instance to the same socket:
nvim --listen /tmp/custom-nvim-socket
Tool | Description |
| File outline via LSP (with optional name filter) |
| Treesitter Abstract syntaxt tree at a cursor position |
| Workspace-wide symbol search via LSP |
| LSP errors/warnings for a file or workspace |
| Find all usages of a symbol |
| Jump to where a symbol is defined |
| Find implementations of an interface/abstract method |
| Type signature and docs at a position for a symbol |
| Read/write the Neovim quickfix list |
| Restart LSP clients (useful after external file changes) |
| get active LSP clients |
| Check connection with the Neovim instance |
Project | Diffs |
mcp-neovim-server is about overall control of your Neovim instance, with focus on text editing. This project focuses only on code navigation instead. |
See src/README.md for project structure and how to add new tools.
Get the treesitter scope chain at a position (shows enclosing functions, classes, blocks)
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute or relative file path | |
| line | Yes | Line number (1-indexed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes the operation as a read ('get') and specifies the output content (scope chain). However, it lacks details on potential side effects (none expected), performance, or limitations beyond the given explanation.
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?
A single, well-structured sentence that leads with the verb and resource. Every word serves a purpose; no 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?
No output schema exists, so description should explain return format. It mentions 'scope chain' and 'shows enclosing...', which is somewhat complete for a simple tool, but lacks details on whether output is a list, tree, or something else. Could be more explicit for full completeness.
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% as both parameters have descriptions. The tool description does not add extra meaning beyond what the schema provides for file and line. Baseline 3 is appropriate since the description adds no parameter-specific detail.
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 verb 'Get' and resource 'treesitter scope chain at a position', and explicitly lists what it shows (enclosing functions, classes, blocks). It is distinct from sibling tools which are LSP-based (e.g., get_document_symbols, hover).
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. The description implies it is for code structure context but does not mention when not to use it or which sibling tool to prefer for different tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get LSP diagnostics (errors, warnings) for a file or the entire workspace
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | File path to filter diagnostics (omit for all) | |
| severity | No | Minimum severity level |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states what the tool retrieves but does not disclose behavioral traits such as whether it is read-only, if it requires a running LSP server, or what happens on failure.
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 with no redundant words. However, it could be slightly more structured by separating scope and parameters.
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 2 optional parameters and no output schema. The description does not explain the return format or any side effects. For a diagnostic tool, more detail about the output structure would be helpful.
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%. The description does not add meaning beyond the schema; the schema already explains both parameters ('file' and 'severity'). The description's mention of 'file or workspace' is echoed 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 verb 'Get', the resource 'LSP diagnostics', and specifies the scope ('for a file or the entire workspace'). It distinguishes this tool from siblings like 'get_document_symbols' or 'get_references' by focusing on diagnostics.
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 the tool (to get diagnostics for a file or workspace) but does not explicitly state when not to use it or mention alternatives like 'get_quickfix'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get LSP document symbols for a file (functions, classes, types with line numbers and nesting). Optionally filter by name.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Absolute or relative file path | |
| query | No | Filter symbols by name (case-insensitive substring match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that symbols come with line numbers and nesting, but does not mention prerequisites (e.g., LSP server must be running), side effects, or limitations. For a read-only tool, some safety context is missing.
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 that front-loads the core action and result. It is concise with no unnecessary 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?
For a simple tool with 2 parameters and no output schema, the description covers the main purpose and optional filter. It could mention the return type (e.g., list of symbol objects) but the implied structure 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?
Schema coverage is 100%, but the description adds value by specifying that the 'query' parameter performs a case-insensitive substring match, which is not in the schema. This additional detail aids correct usage.
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 retrieves LSP document symbols for a file, listing functions, classes, types with line numbers and nesting, and optionally filtering by name. This specific verb-resource combination distinguishes it from sibling tools like workspace_symbols which likely have broader scope.
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 use for file-level symbol retrieval but does not explicitly compare to alternatives such as workspace_symbols (broader scope) or get_ast_context. No when-to-use or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get all running LSP clients and all available ones
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It implies a read-only operation but does not disclose potential side effects, permissions, or what constitutes 'available' clients. The description is minimal.
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, efficient sentence that front-loads the core purpose. Every word earns its place with no 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?
Given no output schema, the description should clarify the return format or structure. It only mentions two categories of clients but omits details like whether names, ids, or full objects are returned. This is adequate but not comprehensive.
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%. The description adds meaning by specifying the output (running and available LSP clients) 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 retrieves LSP clients, distinguishing between running and available ones. It uses a specific verb and resource, and while it doesn't explicitly distinguish from siblings like start_lsp or restart_lsp, the purpose is clear.
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 provided on when to use this tool versus alternatives such as start_lsp or set_quickfix. There is no context about prerequisites or when it is appropriate to call get_lsp.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current Neovim quickfix list contents
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but only states a simple read operation. It does not mention potential side effects, return value behavior (e.g., empty list), or impact on Neovim 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 concise sentence that directly communicates the tool's action and resource, with 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 no output schema, the description should provide some indication of the return structure. 'Contents' is vague and does not clarify whether the result is a list of items or a formatted string, leaving the agent uncertain about the response format.
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, so schema coverage is trivially 100%. The description adds context by specifying the target resource, earning a baseline of 4 for 0-parameter tools.
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 verb 'Get' and the resource 'current Neovim quickfix list contents', which distinguishes it from sibling tools like 'set_quickfix' that perform opposite actions.
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 no guidance on when to use this tool versus alternatives such as 'get_diagnostics' or 'get_references', which exist among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all references to a symbol at a given position via LSP
| Name | Required | Description | Default |
|---|---|---|---|
| col | Yes | Column number (1-indexed) | |
| file | Yes | Absolute file path | |
| line | Yes | Line number (1-indexed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states the basic behavior but omits important details such as whether the LSP server must be running, potential latency, response format, or behavior when no references are found.
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 highly concise: one sentence that conveys the essential purpose without any extraneous words. It is appropriately front-loaded and every word 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?
Given the complexity of a reference-finding tool and the lack of an output schema, the description is incomplete. It does not explain what the result contains (e.g., locations in files), how to interpret the output, or any constraints (e.g., only works for programming languages with LSP support).
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 description does not need to add parameter details. However, it adds no additional context beyond what the schema already provides (e.g., that file is an absolute path and line/col are 1-indexed). Thus, it meets the baseline but does not exceed it.
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 (find all references), the target (a symbol at a given position), and the mechanism (via LSP). It effectively differentiates from sibling tools like goto_definition or hover, 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?
No guidance is provided on when to use this tool versus its siblings (e.g., when to use workspace_symbols for broader searches). There is no mention of prerequisites like the LSP server needing to be active, which is critical for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Go to definition of a symbol at a given position via LSP
| Name | Required | Description | Default |
|---|---|---|---|
| col | Yes | Column number (1-indexed) | |
| file | Yes | Absolute file path | |
| line | Yes | Line number (1-indexed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must describe all behavioral traits. It only says 'go to definition' without explaining side effects (e.g., whether it opens a file, returns a location, or highlights). The agent cannot predict the tool's full 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 a single sentence that is front-loaded and contains no wasted words. However, it could be slightly expanded to include behavioral hints without losing 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 no output schema, the description should clarify what the tool returns or does (e.g., open location, return range). It lacks this information, making it incomplete for an AI agent to understand the call's outcome.
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 parameters 'file', 'line', and 'col' are already fully described. The description adds no additional meaning beyond 'at a given position', which is already implied by 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 action ('Go to definition') and the resource ('symbol at a given position via LSP'). It effectively distinguishes from siblings like 'get_references' or 'goto_implementation' by specifying the exact navigation target.
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 provided on when to use this tool versus alternatives such as 'get_references' or 'hover'. The agent receives no context about prerequisites, typical use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find implementations of an interface or abstract method via LSP
| Name | Required | Description | Default |
|---|---|---|---|
| col | Yes | Column number (1-indexed) | |
| file | Yes | Absolute file path | |
| line | Yes | Line number (1-indexed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only mentions the LSP mechanism, but does not disclose limitations (e.g., language support, behavior when no implementations exist, or potential side effects). This is minimal transparency.
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, efficient sentence of 10 words. No extraneous information, perfectly front-loaded with the core action.
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 tool with no output schema and only 3 well-documented parameters, the description provides adequate context (purpose and mechanism). It may be slightly lacking for edge cases (e.g., multiple implementations), but overall complete.
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% with descriptions for each parameter (file, line, col). The description adds context that these are used for position specification, but does not significantly extend beyond the schema. Baseline 3 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 finds implementations of an interface or abstract method via LSP. It uses a specific verb ('Find') and resource ('implementations'), and the mention of 'interface or abstract method' distinguishes it from sibling tools like goto_definition or get_references.
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 when needing to locate concrete implementations via LSP, and the sibling list provides alternatives. However, it does not explicitly state when not to use it or provide exclusions (e.g., for regular methods).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get LSP hover information (type signature, documentation) for a symbol at a position
| Name | Required | Description | Default |
|---|---|---|---|
| col | Yes | Column number (1-indexed) | |
| file | Yes | Absolute file path | |
| line | Yes | Line number (1-indexed) |
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 does not mention that this is a read-only operation, nor does it specify prerequisites like a running LSP server. The description only states the output type without behavioral context.
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 that directly conveys the tool's purpose. Every word is necessary and no fluff.
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 description explains the return content (type signature, documentation) but does not address prerequisites (e.g., LSP must be started), error handling, or how to interpret results. Given no output schema or annotations, more context would be beneficial.
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 does not add meaning beyond the schema; it only mentions the output. It does not clarify parameter semantics beyond what the schema already provides.
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 retrieves LSP hover information (type signature and documentation) for a symbol at a given position. It uses specific verbs and resource details, and it is distinct from sibling tools like get_references or goto_definition.
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 explains what the tool does but does not provide explicit guidance on when to use it versus alternatives. The context is implied but lacks exclusions or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart all running LSP clients. Use after making changes to files outside Neovim to refresh diagnostics and symbol data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains that the tool restarts all LSP clients and refreshes diagnostics and symbol data. However, it does not disclose potential side effects (e.g., whether running LSPs need to reinitialize or if there are any risks). Given the simplicity of the tool, this is acceptable but not fully 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 with no extraneous text. It front-loads the action and then provides usage context.
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 has no parameters or output schema, the description adequately covers purpose and usage. It could be more complete by mentioning that it affects all clients, but it 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 schea has zero parameters, so the baseline is 4. The description does not need to add parameter information.
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 verb 'restart' and the resource 'all running LSP clients', and it distinguishes from siblings like 'start_lsp' by specifying the action applies to all clients.
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 suggests using the tool after making changes to files outside Neovim to refresh diagnostics and symbol data, providing clear context. It does not specify when not to use it, but the guidance is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the Neovim quickfix list with a list of locations (e.g. feature touchpoints, search results, related code sites)
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | List of locations to populate the quickfix list | |
| title | No | Title for the quickfix list |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action. It does not disclose whether the list is overwritten or appended, what happens with invalid paths, or any side effects.
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?
Single sentence of 12 words, front-loaded with verb and resource, no redundancy. Every word contributes to purpose.
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?
Lacks important context: whether it replaces or appends, if file paths must exist, or what the return value is. No output schema; description should clarify behavior but does 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 coverage is 100%, so parameters are fully defined. The description merely reiterates 'list of locations' without adding new meaning, meeting baseline.
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 'Set the Neovim quickfix list' with specific resources and examples ('feature touchpoints, search results, related code sites'). It distinguishes from sibling 'get_quickfix' by implication, but does not explicitly contrast.
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 on when to use this tool versus alternatives like 'get_quickfix' or other navigation tools. The examples suggest use cases but no explicit when-to-use or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
start a specific LSP server
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | LSP name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only says 'start' with no details on side effects, permissions, or error states. This is insufficient for an action 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 very short and front-loaded, but it lacks important details. It earns its place but could be expanded without losing 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 lack of output schema and annotations, the description does not cover behavioral context like return values, error handling, or prerequisites. It is insufficient for a tool with no other documentation.
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 baseline is 3. The description adds no extra meaning beyond the schema's 'LSP name' 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 clearly states the verb 'start' and resource 'LSP server', distinguishing it from siblings like restart_lsp or get_lsp. However, 'specific' is vague and could be more explicit.
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 on when to use this tool versus alternatives like restart_lsp or when prerequisites are needed. The description lacks usage context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check Neovim connection health
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'check connection health' but does not detail what checks are performed, what constitutes healthy, or any side effects. This is minimal 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 a single concise sentence, front-loaded with the purpose. While efficient, it could include a bit more context without becoming verbose.
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 no parameters and no output schema, the description is minimal. It adequately conveys the core purpose but lacks details on what the health check entails or its return value. For a simple tool, this is just adequate.
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 no parameters, and the schema coverage is 100%. According to instructions, zero parameters yield a baseline of 4. The description does not need to add parameter info as there are none.
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: check Neovim connection health. It uses a specific verb and resource, and distinguishes it from sibling tools that focus on LSP actions, diagnostics, symbols, etc.
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. The usage is implied (checking health), but no exclusions or when-not-to-use are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search workspace symbols via LSP (functions, classes, types across the project)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Symbol name or pattern to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions LSP-based search but does not disclose potential behavioral traits like LSP startup requirements, performance implications, or error scenarios.
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?
Single sentence that is front-loaded with purpose and includes key scope details. No unnecessary 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 the simple tool (1 parameter, no output schema, no annotations), the description provides the basic purpose. However, it lacks information about output format, result limits, or behavior when LSP is not ready, which could be important for agent use.
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% (one parameter with description). The description adds context about what is searched (via LSP, symbol types) but does not extend beyond the schema's parameter description meaningfully, meeting the baseline.
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 (search) and resource (workspace symbols) with scope (across the project). It mentions symbol types (functions, classes, types) but does not explicitly differentiate from sibling tools like get_document_symbols, which is a minor gap.
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 on when to use this tool versus alternatives. The description only states what it does, with no context on prerequisites, limitations, or when it might be inappropriate.
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.
v0.2.0get_ast_contextget_diagnosticsget_document_symbolsget_lspget_quickfixget_referencesgoto_definitiongoto_implementationhoverrestart_lspset_quickfixstart_lspvim_healthworkspace_symbolsScored across 14 tools
Each tool targets a distinct action: LSP diagnostics, symbols, references, definitions, implementations, hover info, and workspace symbols are all clearly separate. AST context, quickfix management, LSP client control, and health check are also unique, so no overlap.
Most tools follow a verb_noun pattern in snake_case (e.g., get_diagnostics, goto_definition). However, 'workspace_symbols' lacks a verb prefix unlike its counterpart 'get_document_symbols', and 'vim_health' could be more descriptive. Overall, the naming is mostly consistent.
14 tools is well-scoped for a Neovim MCP server covering LSP interactions, AST queries, quickfix operations, and server health. Each tool serves a clear purpose without unnecessary bloat or deficiency.
The toolset thoroughly covers code navigation and LSP features (symbols, references, definitions, diagnostics, hover). Missing features like code actions or formatting, but these are likely out of scope for a read-only assistant. Minor gap: no way to get buffer content or edit files.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Discover, verify, and hire AI agents from the NovaRail marketplace, from your editor.