A
licenseB
qualityC
maintenanceLeverages Vim's native text editing commands and workflows, which Claude already understands, to create a lightweight code assistance layer.
19
48
318
MIT
nvim-mcp
nvim-mcp is an MCP server that gives AI agents full programmatic access to a running Neovim session via its native msgpack-RPC socket, enabling them to view, edit, and manipulate code as if directly using the editor.
Connect to Neovim: Auto-discover and connect to one or more running Neovim instances by index, socket path, or terminal PID.
Run Ex commands: Execute any Vim/Neovim ex command (e.g.,
:w,:vsplit,:lua ...), single or batched.Send keystrokes: Send raw key sequences for navigation, mode switching, and triggering mappings.
Get session state: Retrieve a full snapshot including mode, CWD, open buffers, window layout, cursor position, folds, visual selections, marks, diagnostics summary, and active highlights.
Read buffer contents: Read an entire in-memory buffer or a specific line range, with line numbers.
Edit buffers: Perform find-and-replace (must match exactly once) or overwrite entire buffer contents — all in-memory with full undo support, nothing written to disk until explicitly saved.
Get LSP diagnostics: Retrieve errors, warnings, hints, and info from LSP for all buffers or a specific file.
Highlight lines: Annotate specific line ranges with colored extmarks (without modifying content), apply multiple highlights simultaneously, and clear them when done.
Allows AI assistants to control a running Neovim session by sending ex commands, Vimscript expressions, and key sequences; retrieving structured state snapshots including current file, cursor position, mode, window layout, and modified buffers; managing connections to specific instances; and browsing operation recipes for files, navigation, buffers, windows, marks, registers, folds, and LSP actions.
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., "@nvim-mcpgo to definition of the function under cursor"
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.
nvim-mcp
An MCP server that gives AI agents first-class access to your running Neovim session. It connects through Neovim's native msgpack-RPC socket — no plugins required.
Works with Cursor, Claude Code, Codex, OpenCode, and any MCP-compatible client.
Before you connect an agent to Neovim, please read Working safely.
What agents can do
See what you see — editor mode, working directory, open buffers, window layout, cursor context, folds, selections, marks, and diagnostics.
Edit buffers in memory — find-and-replace or full rewrites with immediate feedback and full undo support. Nothing touches disk until you save.
Run any Vim command —
:w,:e,:vsplit, macros, or anything else you could type at the command line.Send keystrokes — navigate, enter insert mode, trigger mappings.
Query LSP diagnostics — errors, warnings, and hints across one buffer or the whole session.
Annotate code with highlights and virtual text — colored line highlights and inline/above/below text notes that never touch the buffer's real content.
Work with multiple instances — auto-discovers running sessions and connects to the right one. See multiple instances.
Anything you can do in Neovim, the agent can too. See the full tool reference for details.
Related MCP server: neovim-mcp
Demos
Quick start
nvim-mcp runs via uv (recommended) or Nix.
Cursor users: A Marketplace plugin is pending review — once available, it installs the MCP server and agent rule together (you can skip to step 4). To activate the rule, start chats with something like "Connect to my Neovim instance" — or set the rule to "Always" in Settings → Rules to apply it on every turn.
Install a launcher.
curl -LsSf https://astral.sh/uv/install.sh | shInstall Nix — flakes must be enabled.
Register the MCP server with your client. Example for Cursor (
.cursor/mcp.json):{ "mcpServers": { "nvim-mcp": { "command": "uvx", "args": ["nvim-mcp"] } } }{ "mcpServers": { "nvim-mcp": { "command": "nix", "args": ["run", "github:paulburgess1357/nvim-mcp"] } } }For Claude Code, Codex, Claude Desktop, OpenCode, and other clients, see the configuration guide.
Add agent rules — do not skip this. Without rules, the agent has the tools but doesn't know when or how to use them, and behavior will be unreliable. See the configuration guide for setup.
Start Neovim — on most Linux systems it listens on a Unix socket automatically and is discovered by nvim-mcp. If auto-discovery doesn't work, see environment variables. Running multiple instances? See multiple instances.
Verify it works
Open a file in Neovim and paste this into your AI agent:
For each step: explain what you're about to do, then do it, then tell me
what happened. Wait for me to say "next" before moving on.
1. What file am I in? Highlight the function my cursor is in.
2. Are there any diagnostics? Highlight any lines with errors or warnings.
3. Add a docstring above the function, then show me the diff.
4. Open a vertical split, write a short test for that function, and save both files.Working safely
The tools and agent rules are designed to use non-destructive operations — edits happen in memory, undo history is preserved, and the agent is steered toward buffer operations. But LLMs are non-deterministic, have full access to Neovim's API, and you should assume they will make mistakes. Work in a version-controlled directory.
Requirements
Linux
Python ≥ 3.10
Neovim ≥ 0.11 (older versions work with
--listenandNVIM_ADDRESS)
License
MIT — see LICENSE.
Available Tools
18 toolsadd_virtual_textA
Add a virtual text annotation to a Neovim buffer. Visual only — the buffer's actual content is unchanged and nothing is written to disk. Annotations stack; multiple calls accumulate.
file: path relative to Neovim's cwd (as shown in get_state buffers).
The buffer must already be open in Neovim; returns an error otherwise.
line: 1-indexed anchor line. Out-of-range values are clamped.
text: list of strings, one per virtual line. Must be non-empty.
When position is "eol", exactly one item is allowed.
position: where the annotation appears relative to the anchor line.
One of "eol" (after end of line), "above" (between previous and
anchor lines), or "below" (between anchor and next lines).
Defaults to "eol".
color: a Neovim highlight group name (e.g. "Comment",
"DiagnosticError") or a hex color (e.g. "#7a9ad4"). Defaults to
"Comment", which adapts to the user's colorscheme. Unknown names
(including bare color literals like "Red") return an error.
Use this for a single annotation. Use add_virtual_texts for
multiple annotations in one call. Use clear_virtual_texts to
remove all MCP virtual text from a buffer.
Returns {added: 1} on success, or {error} with a message on failure.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| text | Yes | ||
| color | No | Comment | |
| position | No | eol |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: annotations stack, buffer must be open, line clamping, text constraints per position, and error conditions for unknown colors and missing buffer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: purpose upfront, visual-only note, parameter details, sibling references, and return value. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers all aspects: parameter behavior, error handling, stacking, and return format. It is sufficiently complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains each parameter in detail: file path relative to cwd, line indexing and clamping, text array constraints, position options with default, and color type with default and error handling. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a virtual text annotation to a Neovim buffer, emphasizing it is visual-only and does not alter the buffer's content. It explicitly distinguishes from siblings like add_virtual_texts and clear_virtual_texts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs alternatives: 'Use this for a single annotation. Use add_virtual_texts for multiple annotations in one call. Use clear_virtual_texts to remove all MCP virtual text from a buffer.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add_virtual_textsA
Add multiple virtual text annotations to Neovim buffers in a single call. Visual only — buffer content is unchanged. Annotations stack; calling this adds more without removing previous ones.
items: a list of dicts. Each dict requires:
file: path relative to Neovim's cwd. Buffer must be open.
line: 1-indexed anchor line. Out-of-range values are clamped.
text: list of strings, one per virtual line. Non-empty. EOL position requires exactly one item. And optionally:
position: "eol" (default), "above", or "below".
color: hex color (e.g. "#7a9ad4") or Neovim highlight group name (e.g. "Comment", "DiagnosticError"). Defaults to "Comment". Unknown names (including bare color literals like "Red") return an error.
Use this when you need to add several annotations at once (possibly
across different files). Use add_virtual_text for a single
annotation. Use clear_virtual_texts to remove all MCP virtual
text from a buffer.
Returns a list of {added: 1} results in input order. Raises a
ValueError if any item is missing a required key. Iteration is
sequential: if item N fails validation or the manager raises,
items 0..N-1 have already been applied (call clear_virtual_texts
to roll back).
Example: [{"file": "foo.py", "line": 10, "text": ["this is the bug"]}, {"file": "foo.py", "line": 20, "text": ["note one", "note two"], "position": "above", "color": "DiagnosticInfo"}]
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly discloses behavioral traits: visual only, stacking behavior, clamping of out-of-range lines, position options, color behavior (including error on unknown names), and the critical fact that partial application occurs on failure with rollback via clear_virtual_texts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: purpose first, then structured parameter breakdown, then usage guidance and example. Every sentence adds value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple items, nested fields, side effects), the description covers input format, constraints, error handling, return format, and partial application behavior. It is complete and leaves no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by detailing each field in the items list, including required vs optional, types, defaults, and a concrete example. This adds significant meaning beyond the minimal schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds multiple virtual text annotations to Neovim buffers in a single call, and explicitly distinguishes it from sibling tools (add_virtual_text for single, clear_virtual_texts for removal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool ('when you need to add several annotations at once') and when to use alternatives, including direct references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clear_highlightsA
Remove all MCP highlights from a Neovim buffer. Only removes
highlights added by highlight_range or highlight_ranges — does
not affect syntax highlighting, LSP highlights, or other plugins.
Does not modify buffer content. Safe to call even if no highlights
are present (returns {cleared: true} either way).
file: path relative to Neovim's cwd (as shown in get_state buffers).
The buffer must already be open in Neovim; returns an error otherwise.
Use this to clean up highlights after an annotation workflow.
Use highlight_range or highlight_ranges to add highlights.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses all relevant behaviors: only removes MCP highlights, no buffer content modification, safe when no highlights are present, returns a success object, and errors if the buffer is not open. This fully compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs with no wasted words. The first paragraph covers the core purpose and safety, the second covers the parameter. It is front-loaded with the key action. Minor redundancy could be trimmed, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and no output schema, the description covers the return value, error condition, and relationship to sibling tools. It is nearly complete; a minor gap is not detailing the error format for non-open buffers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds essential meaning: 'file' must be a path relative to Neovim's cwd, must correspond to an open buffer (as shown in `get_state`), and returns an error otherwise. This goes beyond the raw schema but could be slightly more detailed (e.g., mentioning it is a string).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states: 'Remove all MCP highlights from a Neovim buffer.' It uses a specific verb and resource, and distinguishes from syntax/LSP highlights, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this to clean up highlights after an annotation workflow' and specifies it only removes highlights added by `highlight_range` or `highlight_ranges`, providing clear usage context. It does not explicitly list alternatives but sibling tools imply them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clear_virtual_textsA
Remove all MCP virtual text annotations from a Neovim buffer.
Only removes annotations added by add_virtual_text or
add_virtual_texts — does not affect highlights, LSP virtual
text, inlay hints, or other plugins. Does not modify buffer
content. Safe to call even if no annotations are present
(returns {cleared: true} either way).
file: path relative to Neovim's cwd (as shown in get_state buffers).
The buffer must already be open in Neovim; returns an error otherwise.
Use this to clean up after an annotation workflow. Use
add_virtual_text or add_virtual_texts to add annotations.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fully compensates. Discloses what it removes/doesn't remove, that it doesn't modify buffer content, idempotency, return value, and error condition for non-open buffer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs: first covers purpose and scope in three sentences, second explains the parameter. Every sentence adds necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple tool (one param, no output schema), description covers all aspects: purpose, parameter, return value, error condition, and safe usage. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description fully explains the 'file' parameter: path relative to cwd, reference to get_state, and requirement that buffer must be open.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Remove' and resource 'MCP virtual text annotations from a Neovim buffer'. Distinguishes from siblings by specifying it only removes annotations added by add_virtual_text or add_virtual_texts, not affecting highlights, LSP, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to clean up after an annotation workflow' and references sibling tools for adding. States it's safe to call even with no annotations. Could be more specific about when not to use (e.g., use clear_highlights for highlights), but overall clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
connectA
Connect to a running Neovim instance over its Unix socket or TCP address.
Call this before any other tool if the agent is not yet connected. Connection is persistent for the session; you only need to call it once unless you want to switch instances.
Called with no arguments: auto-connects when exactly one instance is running; returns a list of instances when multiple are found.
Optional selection (provide at most one):
index: pick from the listed instances (1-based).
socket_path: connect directly to a known Unix socket or host:port.
terminal_pid: find the Neovim instance whose process tree contains this PID (useful when Neovim runs inside a specific terminal).
Returns {connected, cwd, file} on success, or {error} with details on failure (e.g. no instances found, connection timeout, bad index).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | ||
| socket_path | No | ||
| terminal_pid | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Fully discloses auto-connect logic, error conditions (no instances, timeout, bad index), and return structure. No annotations present, so description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points, but slightly longer than minimal. Still every sentence adds value and front-loaded with main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: prerequisites (call first), behavior (auto-connect, selection), return values on success/failure, despite no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage (only titles), but description adds semantics for each parameter: index meaning 1-based, socket path as Unix or host:port, terminal_pid as process tree lookup.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Connect to a running Neovim instance' with specific transport methods. Distinguishes from sibling tools like read/write/send commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this before any other tool' and explains when to call with no arguments vs. with selection parameters. Also notes connection is persistent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_and_replace_bufA
Find and replace text in a Neovim buffer. The edit happens in-memory and is fully undoable — nothing is written to disk until the user saves.
file: path relative to Neovim's cwd (as shown in get_state buffers).
old_string: the exact text to find. Must match exactly once in the
buffer; returns an error if not found or if it matches multiple
locations. Include surrounding lines to disambiguate.
new_string: the replacement text.
Creates the buffer if it doesn't already exist. Use this for targeted
edits. Use write_full_buf instead when replacing the entire buffer
content. Use read_full_buf or read_buf_range first if you need
to see the current content before editing.
Returns {start_line, lines_removed, lines_added, total_lines} on success, or {error} with a message on failure.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| new_string | Yes | ||
| old_string | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses in-memory editing, undoability, no disk write until user saves, buffer creation, exact match requirement (error if not found or multiple), and return value structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with summary, parameter details, guidelines, and return value. Slightly verbose but each sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, parameter semantics, behavioral traits, return format, and usage alternatives. No gaps given the tool's complexity and lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds full context for all three parameters: file path relative to cwd, old_string exact match constraints with disambiguation advice, and new_string as replacement. Schema has 0% coverage, description compensates completely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Find and replace text in a Neovim buffer' and distinguishes from siblings by mentioning write_full_buf for full replacement and read_full_buf/read_buf_range for viewing content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use for targeted edits, alternatives for full buffer replacement, and recommends reading first. Also explains undoability and disk persistence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_all_diagnosticsA
Get LSP diagnostics from all open buffers in Neovim. Read-only.
Use this for a project-wide overview of errors and warnings. Use
get_buf_diagnostics instead when you only need diagnostics for a
specific file — it is more focused and returns less data.
Returns a list of {file, line, col, severity, message, source}. severity is one of "error", "warning", "info", "hint". Returns an empty list when there are no diagnostics. Results depend on which LSP servers are attached and which buffers are loaded in Neovim.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return structure, severity levels, empty list case, and dependencies on LSP servers and open buffers. With no annotations, the description fully carries the burden of behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences are perfectly front-loaded: what it does, when to use, and what it returns. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage alternatives, behavioral dependencies, and return format comprehensively. Without an output schema, the description provides all necessary context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% trivially. Description adds no parameter info but is not required; the return format is explained. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves LSP diagnostics from all open buffers, and contrasts with the sibling get_buf_diagnostics by specifying scope. The verb 'get' and resource 'all LSP diagnostics' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends use for project-wide overview and advises using get_buf_diagnostics for a specific file to get more focused data. Provides clear when-to-use and 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.
get_buf_diagnosticsA
Get LSP diagnostics for a single Neovim buffer. Read-only.
file: path relative to Neovim's cwd (as shown in get_state buffers).
The buffer must already be open in Neovim; returns an error otherwise.
Use this when you need diagnostics for one specific file. Use
get_all_diagnostics instead for a project-wide overview.
Returns a list of {file, line, col, severity, message, source}. severity is one of "error", "warning", "info", "hint". Returns an empty list when the buffer has no diagnostics.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only nature, precondition (buffer must be open), and describes return format including severity levels. Fully transparent without annotation reliance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise 5-sentence description with front-loaded purpose. Every sentence adds value: purpose, read-only, parameter semantics, usage guidelines, return format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects for a simple tool: purpose, usage, parameter semantics, return format with severity values, error condition. No gaps despite no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds crucial context beyond schema: 'file path relative to Neovim's cwd (as shown in `get_state` buffers). The buffer must already be open; returns an error otherwise.' Schema has 0% coverage, so description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it gets LSP diagnostics for a single Neovim buffer, distinguishing it from the sibling 'get_all_diagnostics' by specifying 'single' vs 'project-wide'. Verb and resource are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides guidance: 'Use this when you need diagnostics for one specific file. Use `get_all_diagnostics` instead for a project-wide overview.' Also states buffer must be open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_stateA
Full snapshot of the current Neovim session. Read-only — does not modify any editor state.
Use get_state_brief for quick orientation at the start of a turn.
Use this when you need the complete picture: all window details,
folds, marks, diagnostics summaries, highlights, virtual text, and
indent settings.
Returns: mode (normal/insert/visual/etc.), cwd, buffers (relative
paths of all listed buffers), modified_buffers, current_tab, tab_count,
and terminals — a list of open terminal buffers as {buf, name,
visible}, present only when at least one exists (targets for
send_to_terminal).
windows — list of visible windows (current tab only). The active window is always first, the alternate window (previous) is second. Each window entry contains: file (path relative to cwd), filetype, total_lines, modified, buftype ("file" for normal buffers, "terminal", etc.), line, col, indent: {expandtab, shiftwidth, tabstop}. Optional per-window fields (present when applicable):
role: "active" or "alternate".
context: numbered lines surrounding the cursor.
selection: {start_line, start_col, end_line, end_col} in visual modes.
folds: list of [start, end] closed fold ranges.
diagnostics_summary: {error, warning, info, hint} counts.
marks: list of {mark, line, col} for lowercase (a-z) buffer marks.
mcp_highlights: list of {start_line, end_line, color} for active highlights.
mcp_virtual_text: list of {line, position, lines, color} for active virtual text.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.9/5.0
Behavior5/5
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 opens with 'Read-only — does not modify any editor state,' which is a clear and explicit safety declaration. It then details the return structure comprehensively, including optional fields and their conditions, providing transparency about what the agent can expect without 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, front-loaded with purpose and usage, then organized by logical sections (windows, per-window fields, optional fields). Each sentence provides necessary detail about what the tool returns, and the formatting with headings and bullet-like lists enhances scannability without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description must fully explain the return values. It does so exhaustively, covering top-level fields, per-window subfields, and optional fields with their shapes. It also explains relationships (e.g., active window first, alternate second) and conditions (e.g., terminals only present when at least one exists), making the tool completely self-contained for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters, so there are no parameter semantics to explain. The baseline for 0 parameters is 4. The description does not discuss inputs because none exist; it focuses on output, which is appropriate for a parameterless getter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Full snapshot of the current Neovim session,' using a specific verb ('snapshot') and resource ('Neovim session'). It clearly distinguishes this from the sibling 'get_state_brief' by stating that this tool provides the complete picture, including all window details, folds, marks, diagnostics, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use get_state_brief for quick orientation at the start of a turn. Use this when you need the complete picture.' This directly contrasts with an alternative, making the selection criteria clear. It also notes that the terminals field is a target for send_to_terminal, giving additional context for when this tool may be useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_state_briefA
Lightweight snapshot of the Neovim session for quick orientation. Read-only — does not modify any editor state.
Use this at the start of each turn to see what the user is working
on. Use get_state instead when you need the full picture: all
windows, folds, marks, diagnostics summaries, highlights, virtual
text, and indent settings.
Returns: mode (normal/insert/visual/etc.), cwd, buffers (relative paths of all listed buffers), modified_buffers, and active_window: {file, filetype, total_lines, modified, buftype, line, col, context}. context is a short list of numbered lines around the cursor.
If an alternate window exists, also returns alternate_window with
the same fields. When terminal buffers exist, returns terminals — a
list of {buf, name, visible} (targets for send_to_terminal).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It explicitly states 'Read-only — does not modify any editor state' and details conditional return fields (alternate_window, terminals). It also calls itself 'lightweight,' which adds performance context. However, it does not mention potential edge cases or error conditions, leaving a slight gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into purpose, usage, and return details. It is not overly long for the information it conveys, and each sentence earns its place. The format is scannable, with clear sections, though it could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully specifies the return structure, including nested fields, conditional additions, and the meaning of each key. It also covers the tool's role in the broader context, making it complete for both invocation and result interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema is empty and inherently 100% covered. The description appropriately focuses on return value semantics rather than parameters, hitting the baseline 4 for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Lightweight snapshot of the Neovim session for quick orientation.' It also distinguishes itself from the sibling tool `get_state` by positioning this as the 'brief' version, making the tool's purpose and scope explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to 'Use this at the start of each turn' and provides an alternative: 'Use `get_state` instead when you need the full picture.' This gives clear when-to-use and when-not-to-use guidance, with a named sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
highlight_rangeA
Add a colored line highlight to a Neovim buffer. This is a visual annotation only — it does not modify buffer content and is not persisted to disk. Highlights stack; calling this multiple times adds more highlights without removing previous ones.
file: path relative to Neovim's cwd (as shown in get_state buffers).
The buffer must already be open in Neovim; returns an error otherwise.
start_line: first line to highlight (1-indexed, inclusive).
end_line: last line to highlight (1-indexed, inclusive). Out-of-range
values are clamped. If start_line > end_line they are swapped.
color: a hex color (e.g. "#3b4048") or a Neovim highlight group name
(e.g. "Comment", "DiagnosticError"). For groups, the resolved
foreground color becomes the line background — so highlights adapt
to the user's colorscheme. Defaults to "Comment". Unknown names
(including bare color literals like "Red") return an error.
Use this for a single highlight. Use highlight_ranges to apply
multiple highlights in one call. Use clear_highlights to remove
all highlights from a buffer.
Returns {highlighted} with the number of lines highlighted, or {error} with a message on failure.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| color | No | Comment | |
| end_line | Yes | ||
| start_line | Yes |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It explains highlights stack, no persistence, line clamping/swapping, color handling. Lacks mentions of permissions or side effects, but for a non-destructive tool, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose first, then parameter details, usage alternatives, return value. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters (3 required) and no output schema, description explains return value (highlighted count or error). Sufficient for a highlight tool, though missing limits or performance notes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (only titles and types given). Description adds path context, indexing, clamping behavior, color defaults and error conditions, significantly enriching parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a colored line highlight to a Neovim buffer' and distinguishes it as a visual-only annotation. It differentiates from siblings by mentioning highlight_ranges and clear_highlights.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies when to use highlight_ranges (multiple highlights) and clear_highlights (removal). It notes the buffer must be open. No explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
highlight_rangesA
Add colored line highlights to one or more Neovim buffers in a single call. This is a visual annotation only — it does not modify buffer content and is not persisted to disk. Highlights stack; calling this adds more highlights without removing previous ones.
highlights: a list of dicts. Each dict requires:
file: path relative to Neovim's cwd (as shown in
get_state). The buffer must be open in Neovim.start_line: first line (1-indexed, inclusive).
end_line: last line (1-indexed, inclusive).
color (optional): hex color (e.g. "#5f3a3a") or Neovim highlight group name (e.g. "Comment", "DiagnosticError"). For groups, the resolved foreground color becomes the line background. Defaults to "Comment". Unknown names (including bare color literals like "Red") return an error. Out-of-range lines are clamped.
Use this when you need to highlight several ranges at once (possibly
across different files). Use highlight_range for a single range.
Use clear_highlights to remove all highlights from a buffer.
Returns a list of {highlighted} results in the same order as the input. Raises an error if any item is missing required keys.
Example: [{"file": "foo.py", "start_line": 1, "end_line": 3, "color": "DiagnosticError"}, {"file": "foo.py", "start_line": 10, "end_line": 12}]
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| highlights | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses: visual annotation only, no modification or persistence, stacking behavior, error handling for unknown colors and missing keys, and clamping of out-of-range lines. Also mentions return format and error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with separate sections for purpose, parameter details, usage guidance, return info, and example. Not overly long, but the parameter details could be slightly more concise (e.g., bullet points). Still highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (nested objects with 4 keys) and presence of output schema, description covers all needed: purpose, parameter semantics, usage guidelines, behavioral traits, error handling, and example. Complete for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description fully documents the 'highlights' parameter: structure of each dict (file, start_line, end_line, optional color with default and error behaviors), and includes an example. Adds meaning beyond the minimal schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it adds colored line highlights to one or more Neovim buffers in a single call. It distinguishes from sibling tools 'highlight_range' (single range) and 'clear_highlights' (removing). The verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use this when you need to highlight several ranges at once (possibly across different files).' Also provides alternatives: 'Use highlight_range for a single range. Use clear_highlights to remove all highlights.' Clear when to use and when not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_buf_rangeA
Read a specific line range from a Neovim buffer. Read-only; reads from Neovim's in-memory buffer, which may differ from the file on disk if there are unsaved changes.
file: path relative to Neovim's cwd (as shown in get_state buffers).
The buffer must already be open in Neovim; returns an error otherwise.
start_line: first line to read (1-indexed, inclusive).
end_line: last line to read (1-indexed, inclusive). Out-of-range
values are clamped to the buffer bounds. If start_line > end_line
they are swapped automatically.
Use this when you only need a section of a file. Use read_full_buf
instead when you need the entire buffer.
Returns {lines, total_lines}. lines is a list of strings, each prefixed with its 1-based line number (e.g. "10: some code").
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| end_line | Yes | ||
| start_line | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully covers behavior. It discloses read-only nature, reads from in-memory buffer, file path relative to Neovim's cwd, clamping of out-of-range values, swapping of start_line > end_line, and return format {lines, total_lines} with line-number prefix.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
124-word description is concise and well-structured. Purpose and behavior first, then parameter details, usage guidance, and return format. Every sentence provides unique value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description includes return fields and behavior. Covers edge cases (clamping, swapping) and prerequisites (buffer must be open). Complete for a 3-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description adds full meaning. It explains 'file: path relative to Neovim's cwd... must be open', 'start_line: first line to read (1-indexed, inclusive)', 'end_line: last line... clamped, swapped if needed'. This goes far beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Read a specific line range from a Neovim buffer,' specifying verb (read), resource (Neovim buffer), and scope (line range). It distinguishes from sibling 'read_full_buf' by noting when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when you only need a section of a file. Use read_full_buf instead when you need the entire buffer.' Also warns that the buffer must be open in Neovim and reads from in-memory buffer, which may differ from disk.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_full_bufA
Read the full content of a Neovim buffer. Read-only; reads from Neovim's in-memory buffer, which may differ from the file on disk if there are unsaved changes.
file: path relative to Neovim's cwd (as shown in get_state buffers).
The buffer must already be open in Neovim; returns an error otherwise.
Use this when you need to see the entire file. Use read_buf_range
instead when you only need a specific section — it returns less data.
Returns {lines, total_lines}. lines is a list of strings, each prefixed with its 1-based line number (e.g. "1: first line").
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description thoroughly covers behavior: read-only, reads from in-memory buffer (may differ from disk), returns error if buffer not open, and describes return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured. Main action front-loaded, then details in separate sentences. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description fully explains return format (lines, total_lines with line numbers). Covers all behavioral aspects, constraints, and context. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'file' with 0% schema description coverage. Description adds critical meaning: path relative to Neovim's cwd, must be open, error otherwise. Fully compensates for schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Read the full content of a Neovim buffer' with specific verb and resource. Distinguishes from sibling 'read_buf_range' by specifying when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when you need to see the entire file. Use read_buf_range instead when you only need a specific section.' Also notes the buffer must be open in Neovim.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_commandA
Run one or more Vim ex commands in Neovim. This is a mutation tool — commands can modify buffers, files on disk, windows, and editor state.
command: a single command string or a list of strings, without the leading ':'. E.g. "w", "e src/main.py", "42", "wincmd v", "lua vim.print(...)", or ["wincmd p", "e file.py", "wincmd p"].
Use this for editor operations that don't have a dedicated tool
(e.g. saving, opening files, splitting windows, setting options).
Use send_keys instead when you need normal-mode motions or
operator sequences. Use find_and_replace_buf or write_full_buf
for buffer text edits — they are safer and provide undo.
Returns {output} with the command's captured output, or {error} if the command failed. When given a list, returns a list of results in the same order; execution stops on the first error.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses that it is a mutation tool that can modify buffers, files, windows, and editor state. It also explains error handling and list execution behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into paragraphs, front-loading the purpose, then parameter details, usage guidance, and return format. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and existence of an output schema, the description covers all necessary aspects: command syntax, mutation behavior, usage context, and return format (output or error, list support).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 0%, the description thoroughly explains the 'command' parameter: it can be a string or list of strings, without leading ':', with concrete examples like 'w', 'e src/main.py', 'wincmd v'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Run one or more Vim ex commands in Neovim,' which clearly specifies the action and resource. It further distinguishes itself from sibling tools by naming dedicated alternatives for buffer edits and normal-mode motions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool ('for editor operations that don't have a dedicated tool') and when to use alternatives like send_keys or find_and_replace_buf, noting that the latter are safer and provide undo.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_keysA
Send raw keystrokes to Neovim as if typed by the user. This is a mutation tool — keystrokes can modify buffers, change mode, and trigger editor actions.
keys: a string of Vim keystrokes. Esc is prepended automatically, so input always begins in normal mode. Multi-mode sequences must be sent in a single call (e.g. "17GVG", not "17GV" then "G"). Use Vim notation for special keys (e.g. "", "v", "").
Use this for normal-mode motions, visual selections, or operator
sequences. Use send_command for ex commands, and
find_and_replace_buf or write_full_buf for text edits — they
are safer and provide structured results.
Returns {sent} confirming the keys that were dispatched. Keystrokes are fire-and-forget; errors from the resulting Vim actions are not captured in the return value.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keys | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that Esc is prepended, multi-mode sequences must be sent in a single call, and keystrokes are fire-and-forget with errors not captured. No annotations exist, but the description fully covers behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with separate paragraphs for purpose, parameter details, usage guidelines, and return value. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description covers all essential aspects: purpose, usage, parameter semantics, behavior, and return value. It is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'keys' is thoroughly explained: format, automatic Esc prepend, special key notation, and multi-mode constraints. Schema coverage is 0%, but the description adds all necessary semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sends raw keystrokes to Neovim, identifies it as a mutation tool, and distinguishes it from siblings like send_command and find_and_replace_buf.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use this tool (normal-mode motions, visual selections, operator sequences) and when not to, with named alternatives (send_command, find_and_replace_buf, write_full_buf).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_to_terminalA
Type text into a terminal buffer's running program (usually a shell) by writing to its job channel. This is a mutation tool — the text reaches the program's stdin as if typed, but is not executed unless submit is true.
text: the text to send, raw. In most shells an embedded newline acts
like pressing Enter, so multi-line text may execute line by line.
When submit is false, trailing newlines are stripped so nothing
runs by accident.
terminal: which terminal to target — a buffer number or buffer name,
as listed under terminals in get_state / get_state_brief.
Names match exactly first, then by unique substring. Omit it when
exactly one terminal exists; with several open, omitting it
returns an error listing them.
submit: false (default) leaves the text at the prompt for the user
to review and press Enter. true appends a carriage return so the
program executes it immediately. NEVER pass submit=true unless
the user has explicitly asked for the command to be run — "put",
"paste", "type", or "prepare" a command always means
submit=false. Suggesting a command yourself is not permission to
run it. When in doubt, use submit=false and let the user press
Enter.
Use this whenever text needs to go into a terminal. It works
regardless of focus, mode, or visibility and never moves the user's
cursor — unlike send_keys, which requires focusing the terminal
and juggling modes. Terminal buffers cannot be edited with the
buffer tools.
Returns {sent, terminal, buf, submitted} on success — sent is the
byte count actually written. On failure returns {error}, including
a terminals list when the target was missing or ambiguous.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| submit | No | ||
| terminal | No |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral transparency burden. It discloses that this is a mutation tool, explains under what conditions text is executed versus merely placed at the prompt, notes newline stripping when submit is false, describes terminal-target matching fallback to error with a list, and reports the exact return shape on success and failure. No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place. It is front-loaded with the core action, then organized by parameter, then usage guidance, then return values. No redundant phrases or filler; the length is justified by the safety-critical nature and need for precise behavioral nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and no output schema, the description is remarkably complete. It covers mutation risk, execution control, parameter disambiguation, error behavior, and return values. It even anticipates ambiguities like multiple terminals and safety-critical submit semantics, making it sufficient for an agent to invoke correctly in varied contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates thoroughly. It explains the 'text' parameter with newline and execution semantics, 'terminal' with matching rules and omission behavior, and 'submit' with defaults, execution implications, and explicit safety rules. This is far more useful than any schema description could be.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Type text into a terminal buffer's running program' and immediately distinguishes it from siblings by noting it writes via the job channel, unlike send_keys or buffer edit tools. This clearly identifies what the tool does and how it differs from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Use this whenever text needs to go into a terminal') and gives direct exclusions: 'unlike send_keys' and 'Terminal buffers cannot be edited with the buffer tools.' It also provides strong safety guidance about submit=false vs submit=true, with concrete examples of when not to use submit=true.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_full_bufA
Replace the entire content of a Neovim buffer. The edit happens in-memory and is fully undoable — nothing is written to disk until the user saves.
file: path relative to Neovim's cwd (as shown in get_state buffers).
content: the full new text for the buffer.
Creates the buffer if it doesn't already exist. Use this when you
need to rewrite the whole file. Use find_and_replace_buf instead
for targeted edits that preserve surrounding content.
Returns {total_lines} with the new line count.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| content | Yes |
TDQS
A4.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses edit is in-memory, undoable, not written to disk until user saves, and creates buffer if missing. Could mention error handling but overall very transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs, front-loaded with core purpose. Every sentence provides value: purpose, behavior, usage guidance, parameter descriptions, and return value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema and simple 2-param input, the description covers purpose, behavior, usage, parameters, and return structure ({total_lines}). Sufficiently complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet description explains 'file: path relative to Neovim's cwd (as shown in get_state buffers)' and 'content: the full new text for the buffer.' Adds essential context beyond schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Replace the entire content of a Neovim buffer' with specific verb and resource. Differentiates from sibling by contrasting with find_and_replace_buf.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool (rewrite whole file) and when to use alternative (find_and_replace_buf for targeted edits). Provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
A4.9/5.0
Disambiguation5/5
All tools have clearly distinct purposes: highlights have separate add/clear, reading has range/full, state has full/brief, editing has targeted replace/full rewrite, diagnostics have single/all, and commands/keys are distinct. No ambiguity.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern in snake_case (e.g., clear_highlights, read_buf_range, send_command). No mixing of conventions.
Tool Count5/5
14 tools is well within the ideal 3-15 range for a Neovim control server. Each tool serves a necessary function without bloat.
Completeness5/5
The tool surface covers all core Neovim interactions: connection, state inspection, diagnostics, buffer reading/writing, text editing, highlights, and command/keystroke execution. No obvious gaps.
Maintenance
ActivityMaintained
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI agents to navigate code using Neovim's LSP and Treesitter features, and read/write the quickfix list.14
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to control Neovim instances running in tmux sessions.
- AlicenseAqualityBmaintenanceMake Neovim feel like Cursor. This MCP server gives an agent full control over the Neovim session it is running inside, including buffers, windows, diagnostics, LSP language intelligence, and terminals.23MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/paulburgess1357/nvim-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server