Tools Overview

In this chapter you learn the conventions every mcpls tool shares: how code is addressed, what the advisory flags in results mean, and how to read errors. The next chapters then cover the 31 tools by task. Learn these rules once and every tool becomes predictable.

Prerequisites

• A connected client.

The 31 tools at a glance

Every tool is read-only except restart_server, which stops and starts language server processes. Tools that produce edits (rename_symbol, format_document, format_range, get_code_actions) return them without applying them.

If you set mcp.tool_prefix, every name above gains the prefix, as in {tool_prefix}_get_hover.

Addressing code

Most tools take a file_path, which must be an absolute path to a file under a workspace root.

Position-based tools use two integers:

• line: the line number, starting at 1.
• character: the column, starting at 1, counted in UTF-16 code units. For ASCII text this is the character count. See Positions and Encodings for the rest.

Range tools take start_line, start_character, end_line and end_character the same way. The end line must exist in the file.

Addressing a symbol by name

get_hover, get_definition, get_references, go_to_implementation, go_to_type_definition, prepare_call_hierarchy and rename_symbol accept a symbol name instead of a position:

Give exactly one form. A request with both, neither, or half a position is rejected with -32602.

{
  "file_path": "/work/app/src/parser.rs",
  "symbol_name": "Parser::parse",
  "symbol_kind": "method"
}

The result carries resolved_symbol with the name, kind, container, the position that was queried and position_source (selection_range or inferred). mcpls never guesses. A name that matches several symbols, none, or whose identifier cannot be located fails with -32602 and a structured data.resolution:

rename_symbol never produces edits for an ambiguous name. get_signature_help and get_completions take a position only.

Reading results

Truncation

List-returning tools are capped at a fixed maximum. When more exist, the result has truncated: true.

Advisory flags

Two flags never block or filter a result; they tell the assistant when to be careful.

• out_of_workspace is set on each location that falls outside every workspace root, such as the standard library or a dependency. The location is valid; it is simply not under your roots.
• positions_degraded appears when a column could not be converted exactly for a server that does not use UTF-16. "request" means the position you sent reached the server unconverted, so the result may describe a different symbol and should not be trusted. "response" means only returned character offsets may be inexact. The flag is omitted when everything converted exactly.

Indexing and diagnostics flags

Results that depend on the server’s index carry indexing_in_progress, which is true when the server was still indexing during the call, so an empty or partial answer may be incomplete.

Enclosing-symbol context

get_references, get_definition, go_to_implementation, go_to_type_definition, go_to_declaration and get_diagnostics accept context: "none" (the default, no extra work) or "enclosing_symbol". With the second value, each location or diagnostic gains an enclosing_symbol naming the innermost symbol that contains it:

{
  "uri": "file:///work/app/src/parser.rs",
  "range": { "start": { "line": 15, "character": 4 }, "end": { "line": 15, "character": 8 } },
  "enclosing_symbol": {
    "status": "resolved",
    "name_path": ["Parser", "parse"],
    "kind": 6,
    "range": { "start": { "line": 12, "character": 1 }, "end": { "line": 30, "character": 2 } },
    "fidelity": "hierarchical"
  }
}

not_computed and unavailable mean nothing is known; never read them as top level. The lookup costs one documentSymbol request per distinct file, capped at 16 files (or max_documents / 4 when workspace.max_documents is below 64) and a 30 second budget. An enrichment object reports files_enriched, files_skipped and cut_short. The primary result is never affected.

Key naming

Keys that mcpls defines are snake_case. Objects passed through from the language server keep LSP’s casing, such as the Diagnostic items and selectionRange on call hierarchy items.

Arguments

A tool accepts only the arguments its schema declares. An argument name the tool does not declare, such as kinds instead of kind_filter, is rejected with an error that names the first unknown field and lists the accepted ones, instead of being ignored. Every tools/list input schema carries additionalProperties: false, so a schema-validating client sees the same rule. The data field of a call or type hierarchy item stays open, because it is opaque by contract.

Kind filters (kind_filter of workspace_symbol_search and get_code_actions, symbol_kind of the symbol-addressed tools, kind of get_folding_ranges) accept their names in any case, and an unknown or over-long value is rejected as -32602 with the valid values.

Errors

Failures are returned as MCP errors with a code and a message, except malformed arguments, which come back as a tool result with isError: true. Common ones:

See Troubleshooting for the fixes.

What’s Next

Start with Code Intelligence, the tools you will use most.