Server Quality Checklist

Tool Scores

• nvim_lsp_referencesB
  3.3/5.0
  Behavior2/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are present, so the description must carry the full burden. It only states the basic purpose and does not disclose behaviors like read-only nature, potential performance cost, or dependency on a language server.

  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 a single, clear sentence with no unnecessary words. It is appropriately sized for the provided schema and context.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has no output schema and a moderate parameter count, but the description is sparse. It does not mention what the return value looks like (e.g., list of locations) or that position defaults to line/col 1, though these are inferable from the schema and tool purpose.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the parameters are already well-documented. The description adds no extra meaning beyond the schema, which is acceptable given the high coverage.

  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 finds all references to a symbol at a position across the project. This distinguishes it from sibling tools like definition (single jump) and hover (inline info).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance is provided about when to use this tool versus alternatives like nvim_lsp_definition or nvim_lsp_rename. The description does not mention exclusions or prerequisites (e.g., LSP server must be active).

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_open_fileB
  3.3/5.0
  Behavior2/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the burden of disclosing side effects. It mentions returning buffer info but does not disclose that opening a file may replace the current window (as implied by the split parameter default 'none') or create a new buffer, nor does it describe any other behavioral traits.

  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 a single concise sentence that front-loads the primary action and includes the optional behavior and return value, with no redundant words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description adequately covers the core function and return value, but given the absence of an output schema and annotations, it fails to provide usage context (when to use vs alternatives) or important behavioral details like window replacement. It is minimally viable but has clear gaps.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Both parameters are already fully described in the input schema (100% coverage), so the description's mention of 'split or new tab' adds minimal value beyond the schema's enum descriptions. It does not clarify path handling (e.g., relative vs absolute, expansion) or split behavior specifics.

  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 action (open a file), the target application (Neovim), the optional split/tab behavior, and the return value (buffer info). This distinguishes it from sibling tools like nvim_read_buffer (reads existing buffer) and nvim_list_buffers (lists buffers).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides no explicit guidance on when to use this tool versus alternatives like nvim_read_buffer or nvim_list_buffers, nor does it mention any prerequisites or exclusions.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_lsp_definitionA
  3.8/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries the burden of disclosing behavioral traits. It does mention the return format (file, line, column with 1-based indexing), but it does not mention prerequisites such as an active LSP server, failure behavior, or that the operation is read-only.

  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 two short sentences that are front-loaded with the primary action and output detail. There is no redundant phrasing or unnecessary elaboration.

  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 the moderate complexity, the full parameter descriptions in the schema, and the absence of an output schema, the description adequately covers the purpose and return values. It does not cover edge cases like no definition found or server errors, but for a straightforward lookup tool this is a minor gap.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema provides 100% coverage with descriptions for all four parameters (col, line, path, bufnr), including defaults and constraints. The description adds no extra parameter semantics beyond referencing 'a position,' so the baseline of 3 is appropriate.

  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's function with a specific verb and resource: 'Resolve the definition location(s) of the symbol at a position.' It also explains the output format, and it is distinguishable from LSP siblings like hover, references, and rename.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The intended use is implied by the title and description, but no explicit guidance is given about when to use this tool versus alternatives like nvim_lsp_references or nvim_lsp_hover. There are no exclusions or when-not-to-use conditions.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_lsp_document_symbolsA
  3.8/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries the burden of behavioral disclosure. It does share that nesting is reported via 'depth' and that kind and line are included, which is useful. However, it omits potential dependencies (e.g., requiring an active LSP server) and error behavior, leaving some gaps.

  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 a single, well-structured sentence that conveys the main purpose, output contents, and a notable feature (depth). Every word adds value, and it is appropriately front-loaded with the core action.

  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?

  For a simple list tool with one optional parameter and no output schema, the description covers the essential aspects: what symbols are listed and the output fields. It could mention prerequisites like an active LSP server for full completeness, but overall it is sufficient for the tool's simplicity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema provides 100% coverage for the single parameter ('bufnr'), describing it as an optional buffer number. The description does not add additional semantic meaning to this parameter, so the baseline score of 3 is appropriate.

  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 uses a specific verb ('List') and clearly identifies the resource (symbols in a buffer) and the output details (kind, line, nesting depth). It is distinct from sibling LSP tools like hover, definition, and references, leaving no ambiguity about its function.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description clearly states what the tool does, but it does not explicitly indicate when to use it versus other LSP tools or provide exclusions. Usage context is implied (e.g., to inspect buffer structure), but no alternatives or conditions are mentioned.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_commandA
  3.9/5.0
  Behavior2/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states that the tool 'return[s] its captured output,' but fails to warn that Ex commands can have side effects, such as `:write` modifying files or `:bnext` changing the active buffer. This is a significant transparency gap for a command executor that can alter editor state.

  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 sentences, front-loaded with the core action and illustrative examples. No redundant information. Every word earns its place, making it efficiently scannable for an agent.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool is simple with one well-documented parameter, but lacks critical behavioral context around side effects and session scope. The description explains execution and output capture but does not address that commands can permanently modify files or alter Neovim state, which is essential for safe autonomous use. This is adequate but not complete.

  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?

  The input schema already provides a clear description of the `command` parameter (100% coverage), establishing a baseline of 3. The tool description adds value by giving concrete examples of valid Ex commands and clarifying that the leading colon is omitted, which enriches parameter understanding beyond the schema's minimal description.

  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 executes an Ex command, with concrete examples like `:write`, `:bnext`, and `:vsplit foo.txt`. This specific verb+resource combination differentiates it from sibling tools such as nvim_exec_lua (Lua execution) and nvim_eval (Vimscript evaluation). The purpose is unambiguous and immediately actionable.

  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?

  The description implicitly defines usage by limiting scope to Ex commands and providing representative examples. It does not explicitly mention when not to use it or recommend alternatives, but the examples and the tool name make the domain clear. This earns a 4 for clear context without explicit exclusions.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_lsp_code_actionA
  3.9/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description must carry full behavioral disclosure. It does reveal that applyIndex applies an action and is 1-based, but it does not mention side effects of applying, error handling for invalid indices, or prerequisites like an active language server on the buffer. This is a moderate disclosure, not comprehensive.

  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 sentences, front-loaded with the core action ('List the code actions'), and no redundant wording. Every clause adds useful information about list/apply behavior and index semantics.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has no output schema and no annotations, yet the description adequately covers the two modes (list and apply) and the main position parameter. However, it omits the shape of the returned code action list, behavior when no actions exist, and any LSP client prerequisites, leaving gaps for an agent invoking it without prior context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% with each parameter already described. The description only restates applyIndex's purpose ('1-based, from a previous listing') already present in the schema, adding no new semantic detail beyond the structured definitions.

  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 lists LSP code actions (quick fixes, refactors) at a position, and can apply one via applyIndex. This specific verb+resource pairing distinguishes it from siblings like hover, definition, references, rename, and format.

  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?

  The description gives clear context: use this to list/apply code actions at a position, with diagnostics included. It does not explicitly name alternatives or exclusions, but the position-based and apply-index behavior make the intended use unambiguous among the sibling LSP tools.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_terminal_readA
  3.9/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries the behavioral burden. It discloses that the tool reads rendered, not raw, contents and that trailing blank lines are trimmed by default. This adds meaningful context beyond the schema. However, it does not explicitly state read-only/no side effects or error behavior for non-terminal buffers, so not a 5.

  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 a single, concise sentence that front-loads the primary action ('Read the rendered contents') and appends a key behavioral detail (trailing blank line trimming). No wasted words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read tool with two parameters and no output schema, the description covers the core purpose and one behavioral nuance. However, it does not clarify the return format (string vs lines) nor differentiate from nvim_read_buffer explicitly, leaving some contextual gaps for an AI agent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%—both bufnr and stripTrailingBlank have clear descriptions. The tool description does not add any additional parameter-level details; it only mentions the default trimming behavior, which is already in the schema. This meets the baseline for full schema coverage.

  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 reads the rendered contents (scrollback + current screen) of a terminal buffer. This distinguishes it from sibling tools like nvim_read_buffer (likely for normal buffers) and nvim_terminal_send (writes). The verb 'read' and resource 'terminal buffer' 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 Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies this tool is for terminal buffers, but does not explicitly state when to use it over nvim_read_buffer or provide exclusions. For example, it doesn't mention that nvim_read_buffer may not include scrollback or is for non-terminal buffers. Thus, usage guidance is implied but not stated.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_write_bufferA
  3.9/5.0
  Behavior3/5

  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 the core behavior of replacing line ranges but does not disclose side effects (e.g., undo behavior, buffer freshness, or error conditions like buffer-only-open). The description is adequate for simple write operations but lacks depth.

  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?

  One dense sentence that front-loads the purpose and includes critical range details. No unnecessary filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool has 5 parameters with full schema coverage and no output schema, the description is sufficient for the primary use case. However, it does not explain return values or error behavior, which might be expected for a write operation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema covers 100% of parameters with individual descriptions, so baseline is 3. The description adds value by explaining the whole-buffer replacement pattern, but most semantics are already present in 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 action ('Replace a line range in a buffer with new lines') with a specific resource ('buffer') and the line range semantics. It distinguishes from sibling tools like nvim_read_buffer (read) and terminal tools.

  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?

  Provides concrete guidance on line range semantics including the 0-based, end-exclusive convention and the special case for replacing the whole buffer (start=0, end=-1). Does not explicitly mention alternatives or when-not-to-use, but the context is clear and actionable.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_evalA
  4/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  The description focuses on what the tool does (evaluate and return result) but does not disclose potential side effects of executing arbitrary Vimscript, error handling, or whether it is safe/read-only. With no annotations, the description carries full burden but leaves these aspects unaddressed.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, concise sentence that is front-loaded with the core action and includes a useful example. No redundant information.

  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?

  The tool is simple with one parameter, but lacks an output schema. The description says 'return the result' but does not specify the output format (e.g., string, JSON) or error behavior, which would be helpful for an agent. However, the given example gives some clue about expected output.

  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?

  The schema already covers the parameter ('expr' is described as the Vimscript expression). The description adds an example (`expand('%:p')`) that clarifies expected syntax and return type, providing value 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 evaluates a Vimscript expression and returns the result, with a concrete example (`expand('%:p')`). This distinguishes it from sibling tools like nvim_exec_lua (Lua) and nvim_command (Ex commands).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage for Vimscript evaluation, but does not explicitly state when to use it versus alternatives such as nvim_exec_lua or nvim_command. There is no direct comparison or exclusion guidance.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_list_buffersA
  4/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the safety burden. It accurately describes the read-only action of listing buffers and adds a behavioral nuance (terminal buffers report buftype 'terminal'). However, it does not explicitly state that it does not modify state, nor does it mention ordering, pagination, or potential errors, leaving modest gaps.

  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 a single, tightly worded sentence. It front-loads the primary action ('List all buffers') and follows with specific details, containing no fluff or redundant content.

  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 that there is no output schema, the description sufficiently conveys the return fields and the special case for terminal buffers. It lacks an explicit statement of the exact data structure (e.g., array of objects), but for a simple list tool, the enumerated fields provide adequate contextual completeness.

  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?

  The tool has zero parameters, so no parameter documentation is needed. This score reflects the baseline for a parameterless tool where the description does not need to add parameter semantics.

  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 action ('List all buffers') and specifically enumerates the included fields (number, name, type, modified state, line count), making it distinct from sibling tools like nvim_list_windows or nvim_list_terminals. The addition of the terminal buffer behavior further clarifies the scope.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage when buffer information is needed, but it does not explicitly reference alternatives or provide exclusion criteria. There is no guidance on when to prefer this over related tools such as nvim_list_windows or nvim_read_buffer.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_list_terminalsA
  4/5.0
  Behavior3/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 disclosing behavioral traits. It indicates a read-only listing action and describes what is included (job/channel and running state), but it does not disclose potential side effects, error conditions, or any dependency on an active Neovim session. The 'List' verb implies non-destructiveness, but without annotations, richer context would be beneficial.

  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 a single sentence that front-loads the verb and clearly states the object and details. It contains no filler or redundant words, earning every word's place.

  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?

  For a simple zero-parameter listing tool, the description is complete: it states the subject, scope, and included state attributes. There is no output schema, but the description adequately covers return expectations. It could mention whether it returns only visible buffers or includes hidden ones, but that is a minor gap.

  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?

  The tool has zero parameters, so the baseline is 4 as per the rubric. The description adds meaningful context about what is returned (terminal buffers with job/channel and running state), which complements the empty schema. No parameter-specific details are needed.

  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 verb 'List', the resource 'terminal buffers', and the scope 'currently open in Neovim', which distinguishes it from nvim_list_buffers (all buffers) and nvim_open_terminal (which creates terminals). The added detail 'with their job/channel and running state' further clarifies the tool's purpose.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage: use when you need to see terminal buffers and their state. However, it provides no explicit guidance on when to prefer this over nvim_list_buffers, nvim_terminal_send, or other siblings, and no exclusions or prerequisites are mentioned.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_lsp_formatA
  4/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are present, so the description bears the burden. It discloses the key behavioral trait of modifying the buffer in place, which is a mutation. However, it does not mention prerequisites like an active LSP client, reversibility, or failure behavior, leaving some uncertainty for a mutation tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single sentence, front-loaded with the action and resource, and contains no redundant words. Every phrase adds value: 'using its language server' and 'apply the changes in place'.

  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?

  The tool is simple with one optional parameter, no output schema, and no annotations. The description covers the core function and side effect. It is slightly incomplete by not addressing the need for an attached language server or what happens on failure, but these are minor gaps for a straightforward formatting tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100% for the only parameter (bufnr), with the description 'Buffer number. Omit for the current buffer.' The tool description adds no further parameter semantics, so the baseline of 3 applies.

  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 ('Format a buffer') using a specific resource ('its language server') and notes in-place application. This distinguishes it from sibling LSP tools like hover, definition, rename, and code_action, which have different purposes.

  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?

  The description conveys when to use: when you want to format a buffer via LSP. However, it does not explicitly state when not to use it or mention alternative tools (e.g., nvim_lsp_code_action for formatting via code actions). Thus clear context but no exclusions or alternatives.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_lsp_hoverA
  4/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the transparency burden. It states 'Get' implying a read-only operation and 'as the editor's language server would show it' hinting at LSP dependency, but it doesn't disclose prerequisites like an active LSP or buffer requirements (though schema covers the buffer). It doesn't describe failure modes or 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?

  The description is a single concise sentence that front-loads the action ('Get hover documentation') and efficiently conveys the tool's purpose without any filler. Every word contributes.

  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?

  For a read-only tool with all parameters fully described in the schema and a clear purpose, the description is mostly complete. It doesn't fully explain return format or requirements for LSP attachment, but given the low complexity and sibling context, it is adequate.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema documents all four parameters with descriptions, achieving 100% coverage. The description doesn't add meaning beyond the schema, except for the phrase 'at a position' which aligns with the col/line parameters but adds no new detail. Hence baseline 3.

  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 uses a specific verb and resource ('Get hover documentation') and details the content ('signatures, types, docs'). It clearly distinguishes from sibling LSP tools by focusing on hover, not definition, references, or rename.

  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?

  The description clearly implies when to use this tool: when you need hover info for a symbol at a position. It doesn't explicitly list alternatives or exclusions, but the purpose is unambiguous compared to sibling tools, so it earns a 4 for clear context without exclusions.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_list_windowsA
  4.2/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the burden. 'List open windows with their buffer, size and cursor position' clearly indicates a read-only operation and names the returned attributes. However, it does not disclose edge cases, potential errors, or the exact 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?

  The description is a single, front-loaded sentence with no filler or redundancy. It conveys the purpose and output contents efficiently.

  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?

  For a zero-parameter, low-complexity listing tool, the description covers the essential information: what is listed and what fields are included. It does not specify ordering or filtering, but these are not necessary for a basic list operation.

  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?

  The tool has zero parameters, so the baseline is 4. There are no parameter semantics to add beyond the empty schema, and the description correctly focuses on what the tool returns.

  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 uses a specific verb 'List', names the resource 'open windows', and specifies what information is returned (buffer, size, cursor position). This clearly distinguishes it from siblings like nvim_list_buffers or nvim_list_terminals.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage for inspecting open window state, but does not explicitly state when to use this tool versus alternatives or any prerequisites. There is no mention of exclusions or alternative tools.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_read_bufferA
  4.2/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the burden of behavioral disclosure. It adds valuable details about line range semantics (0-based, end-exclusive, end=-1 reading to the end), which is beyond what the schema states. It does not mention return format or error handling, but covers key behavioral traits sufficiently for a simple read operation.

  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 a single, front-loaded sentence that conveys the action, target options, and line range semantics without unnecessary words. Every clause earns its place, making it highly concise and well-structured.

  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?

  For a simple read tool without an output schema, the description covers the essential aspects: target buffer selection and line range behavior. It omits the return format (e.g., array of strings), but given the tool's simplicity and the clarity of the operation, it is reasonably complete. The lack of an output schema makes a return-type note beneficial, but not critical.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 reinforces parameter relationships (e.g., by number/path/current buffer) but does not add significant meaning beyond the schema's own property descriptions. The schema already documents defaults and exclusivity, so the description adds minimal extra value here.

  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 reads lines from a buffer, specifying target by number, path, or current buffer. This distinguishes it from sibling tools like nvim_write_buffer (which writes) and nvim_terminal_read (which reads terminal output), making its purpose unambiguous.

  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?

  The description provides clear context for when to use this tool (to read buffer content) and how to specify the target (by number, path, or current buffer). However, it does not explicitly mention when not to use it or alternatives, though no direct alternatives exist among siblings for reading buffer content.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_run_in_terminalA
  4.2/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden. It discloses key behaviors: opens a terminal inside Neovim, waits for completion, returns output/exit code, and shares the editor's environment and working directory. This adds meaningful context beyond the raw parameter schema, though it could mention timeout behavior or the visual presence of the terminal.

  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 two concise sentences. The first sentence front-loads the primary function and output, while the second adds an example and environmental context. No unnecessary words or repetition.

  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 the six parameters and complete schema descriptions, the tool is reasonably complex, but the description covers the overall workflow and explicitly states the return values (output and exit code) despite no output schema. It could be more complete by contrasting with interactive terminal tools, but it is sufficient for correct selection and use.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% with each parameter having a description, so the baseline is 3. The description adds modest context by noting 'single shell command' and environment sharing, but does not delve into parameter-specific details, leaving the schema to do the heavy lifting.

  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's function: 'run a single shell command, wait for it to finish, and return its output and exit code.' It specifies the verb (run), resource (shell command in terminal), and distinguishes itself from siblings like nvim_open_terminal or nvim_terminal_send by emphasizing the one-shot, wait-and-return behavior.

  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?

  The description positions this as 'the one-shot building block' and provides an example, implying it should be used for non-interactive command execution. However, it does not explicitly name alternative tools or state when not to use it, so it lacks full explicit exclusion guidance.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_exec_luaA
  4.4/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries the full burden. It clearly explains the execution model: the code is a function body requiring `return` to produce a value, and args are accessed via `...`. It also discloses the output format as JSON. It does not explicitly warn about side effects or error handling, but the 'most powerful' phrasing hints at broad capabilities. This is substantial behavioral disclosure for a tool with no annotations.

  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 three sentences with no filler. It front-loads the core function and return format, follows with the critical usage requirement (return and varargs), and ends with capability scope. Every sentence earns its place, making it efficient and easy to parse.

  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?

  Despite no annotations and no output schema, the description is quite complete for a two-parameter tool. It explains the purpose, execution model, return type, and scope. It lacks explicit side-effect warnings and error behavior, but the essential operational details are present. Given the simplicity of the schema, the description is sufficient for an agent to invoke it 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?

  The schema already describes both parameters with 100% coverage. The description adds value by explaining the relationship between the `code` parameter and the function-body semantics, and how `args` maps to `...` in the code. This goes beyond the schema's simple descriptions, providing practical guidance on how to construct calls.

  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 the tool runs Lua via nvim_exec_lua and returns JSON, using a specific verb (Run) and resource (Neovim Lua API). It distinguishes itself from sibling tools like nvim_eval (Vimscript) and nvim_command by emphasizing that any Neovim Lua API call is reachable, which clearly sets it apart. This is specific and actionable.

  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?

  The description gives clear context: it is labeled 'the most powerful tool' with access to everything the Lua API can do, implying it is the general-purpose fallback. However, it does not explicitly say when to prefer alternatives like nvim_eval for Vimscript or nvim_command for commands, nor does it state any exclusions. Thus it provides context but no explicit when/when-not guidance.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_lsp_renameA
  4.4/5.0
  Behavior4/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 behavior disclosure. It explicitly notes that the tool applies edits project-wide and that setting apply=false previews without modifying anything, which is important mutation context. It does not mention permissions or undo, but the core safety behavior is well disclosed.

  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 a single, front-loaded sentence that conveys the core action, scope, mechanism, and a key option without wasted words. It is concise and to the point.

  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 the comprehensive schema with 100% parameter coverage and the description's coverage of the apply/preview behavior, the tool is well explained. There is no output schema, but the description sufficiently conveys what the tool does and its main mode switch, so only minor details like return structure are absent.

  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?

  The schema already covers all parameters with descriptions, giving a baseline of 3. The description adds value by clarifying the practical effect of the apply parameter (preview vs. apply) and by framing the line/col as a position, which goes beyond the raw schema fields.

  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 renames a symbol at a position project-wide via the language server, using a specific verb and resource. It also differentiates this from sibling LSP tools like hover or references by specifying the rename action and its project-wide scope.

  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?

  The description provides clear context for use (renaming symbols project-wide) and gives actionable guidance on the apply parameter to preview changes. It does not explicitly mention alternatives, but no sibling tool provides the same rename capability, so the usage context is clear enough.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_open_terminalA
  4.4/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries the full burden. It discloses key behavioral traits: persistence, return of buffer number/channel/job id, and interaction via send/read. It does not mention side effects like window splitting or process backgrounding, but the phrase 'persistent terminal' implies continued execution. This adds meaningful context beyond the schema, though it could be more detailed about 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 concise: two sentences, front-loaded with the primary action, followed by usage guidance and alternative. Every sentence adds value, with no redundant or filler content.

  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 5 parameters, no output schema, and no annotations, the description is sufficiently complete. It explains the return values (buffer number, channel, job id) and when to use the tool vs siblings. It lacks details about window split behavior or non-blocking nature, but those are less critical and partially covered by schema. Overall the description provides enough context for correct use.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description does not add much beyond schema for parameters—it does not explain cmd, cwd, name, focus, or split semantics. The schema descriptions already cover these, so the description's lack of parameter detail is acceptable.

  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 specific verb+resource: 'Open a persistent terminal inside Neovim and return its buffer number, channel and job id.' It distinguishes itself from sibling nvim_run_in_terminal by emphasizing persistence and long-running sessions, and from nvim_terminal_send/read by mentioning them as complementary tools. The purpose is unambiguous and 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?

  The description explicitly provides usage guidance: 'Use this for interactive or long-running sessions; for one-shot commands prefer nvim_run_in_terminal.' It also names nvim_terminal_send and nvim_terminal_read as the intended follow-up tools, giving clear context for when to use this tool vs alternatives.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_terminal_sendA
  4.4/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries full behavioral disclosure. It explicitly discloses the default carriage return behavior and the enter=false option for raw keys, which are important side effects. It doesn't cover error cases or prerequisites beyond 'open buffer', but this is adequate for a simple send operation.

  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 two well-structured sentences: first states purpose, second explains the key flag behavior. No redundant text or filler, making it highly 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?

  The description covers the tool's purpose, the necessary context (open terminal buffer, bufnr source), and the default behavior. It's sufficient for an agent to invoke correctly given the schema; no output schema is needed. Minor gaps like error handling don't undermine completeness for this simple tool.

  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?

  Schema coverage is 100%, so baseline is 3. The tool description adds meaningful context beyond the schema by explaining that 'enter=false' sends raw keys (e.g., control characters), which isn't in the schema's enter parameter description. This enhancement justifies a 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 the tool sends input to an open terminal buffer, using a specific verb and resource. It distinguishes from sibling tools like nvim_open_terminal (creates) and nvim_terminal_read (reads). The mention of 'open terminal buffer' clarifies it targets existing terminals.

  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?

  The description implies usage context by referring to 'open terminal buffer' and specifying bufnr from nvim_open_terminal/list, indicating a prerequisite. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough for an agent to select this tool for sending input to existing terminals.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_diagnosticsA
  4.5/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries the full burden. It discloses the key behavioral trait of optionally scoping to a buffer, and the read-only nature implied by 'Return'. It could be more explicit about lack of side effects or output structure, but for a simple getter it is reasonably 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 sentences, no fluff. The first sentence states the core function and scope, the second provides a practical use case. Every word earns its place.

  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 low complexity (1 optional parameter, no output schema, no nested objects), the description is sufficiently complete. It covers purpose, parameter behavior, and a use case, so an agent can confidently invoke the tool.

  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?

  Schema coverage is 100% (the bufnr parameter is described), so baseline is 3. The description adds meaning by explaining that omitting the parameter returns diagnostics for all buffers, which reinforces and clarifies the schema's statement. This extra context elevates it above baseline.

  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's function: returning LSP/diagnostic entries for a buffer or all buffers. It uses a specific verb ('Return') and resource ('LSP/diagnostic entries'), and the mention of buffer scoping distinguishes it from sibling LSP tools like nvim_lsp_hover or nvim_lsp_definition.

  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?

  The description offers a clear use case ('letting the agent see and fix problems the way Cursor does'), which implies when to use the tool. However, it does not explicitly compare with alternative tools or state when not to use it, so it falls short of a full 5.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_lsp_clientsA
  4.5/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the transparency burden. It discloses the output fields and the precheck role, implying read-only behavior. However, it does not explicitly state side effects, errors, or behavior with no LSP attached, but 'list' conveys minimal risk.

  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 sentences, front-loaded with the core purpose, then usage guidance. No redundant information or filler.

  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?

  For a simple list tool with one optional parameter and no output schema, the description provides sufficient context: what it lists, what fields are returned, and when to use it. It is complete for an agent to invoke it correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The sole parameter (bufnr) is fully described in the schema ('Buffer number. Omit for the current buffer.'). The description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.

  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 lists LSP clients attached to a buffer, specifying the exact information returned (id, name, root directory, initialization status). It distinguishes from sibling tools which perform hover, definition, references, rename, 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?

  Explicitly states when to use: 'Use this to check language intelligence is available before calling the other nvim_lsp_* tools.' This provides clear usage context and implicitly indicates alternatives (the other LSP tools).

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• nvim_infoA
  4.7/5.0
  Behavior4/5

  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 clearly discloses what the tool reports (version, channel, cwd, buffer/window, connection resolution) and implies a read-only, status-check behavior. It does not explicitly state 'does not modify anything', but the reporting nature is evident.

  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 sentences, front-loaded with the core purpose, followed by a clear usage directive. Every word earns its place; no redundant or filler content.

  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?

  For a zero-parameter tool with no output schema, the description fully covers purpose, content, and usage. It tells the agent exactly what to expect (version, channel, cwd, buffer/window, connection) and when to use it. Nothing critical is missing.

  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?

  The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific details (there are none), but also doesn't need to. The schema has no properties, and the description fully explains what the tool does without requiring parameter context.

  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 uses the specific verb 'Report' and clearly identifies the resource as the connected Neovim instance, listing exact details (version, channel, working directory, buffer/window, connection resolution). This differentiates it from sibling tools focused on LSP, buffers, terminals, 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?

  Explicitly instructs to 'Use this first to confirm the agent is wired to a live Neovim', which establishes a clear primary use case and prioritization among sibling tools. This is strong guidance for when to invoke it.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.