The jons-mcp-java server provides Java language intelligence powered by Eclipse JDT.LS, enabling code navigation, symbol lookup, diagnostics, refactoring previews, and server management for Gradle-based Java workspaces.
Code Navigation:
definition – Navigate to a symbol's definition at a given position
type_definition – Navigate to a symbol's type definition
implementation – Find all concrete implementations of an interface or abstract method
references – Find all references to a symbol across the workspace, with pagination and optional declaration inclusion
Symbol Information & Search:
symbol_info – Get hover-style Javadoc and type information for a symbol
document_symbols – List all symbols (classes, methods, fields, etc.) in a Java file, with pagination
workspace_symbols – Search for symbols by query string across the entire workspace, with pagination
Code Quality & Refactoring:
diagnostics – Fetch fresh compiler diagnostics (errors, warnings) for a Java file, with pagination
preview_rename – Preview a rename refactoring across the project without writing any changes to disk
Server Management:
restart_server – Stop one or all JDT.LS clients and clear runtime state; servers restart lazily on next use
Key Behaviors:
All positions are one-based (line and character)
Paths can be workspace-relative, absolute, or file:// URIs; paths outside the workspace root are rejected
JDT.LS initializes lazily on the first file-backed call and may return an initializing status on first use
Ensures data freshness by tracking open LSP documents and comparing disk metadata before returning results
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., "@jons-mcp-java show me all references to the UserService class"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server that provides Java language intelligence through Eclipse JDT.LS.
Released packages are available from PyPI. Development versions can also be run from a source checkout or directly from GitHub.
The current public API is aligned with jons-mcp-typescript: public positions
are one-based, successful tool responses use structured items and pagination
shapes, and refactoring previews are read-only.
Python 3.10+
Java 21+
Eclipse JDT.LS
A target Java workspace containing Gradle project markers:
settings.gradle, settings.gradle.kts, build.gradle, or build.gradle.kts
On macOS with Homebrew:
brew install openjdk@21 jdtlsIf Java is not on your PATH, set JAVA_HOME. If JDT.LS is installed somewhere
custom, set JDTLS_HOME. The server also tries to resolve a jdtls
executable on PATH.
If JDTLS_HOME points at a read-only install such as the Nix store, the server
copies the small platform config_<os> directory into a writable cache under
$XDG_CACHE_HOME/jons-mcp-java or ~/.cache/jons-mcp-java. Set
JDTLS_CONFIG_DIR to choose a specific writable configuration directory. The
cached copy is repaired to be user-writable even when the source archive or
package ships read-only mode bits.
Related MCP server: JDTLS-MCP
From PyPI:
uvx jons-mcp-java /path/to/java-workspaceFrom a source checkout:
git clone git@github.com:jonmmease/jons-mcp-java.git
cd jons-mcp-java
uv sync
uv run jons-mcp-java /path/to/java-workspaceFrom GitHub without a persistent checkout:
uvx --from git+https://github.com/jonmmease/jons-mcp-java.git \
jons-mcp-java /path/to/java-workspacePass the Java workspace root as the optional positional argument, or set
JONS_MCP_JAVA_WORKSPACE. The positional argument takes precedence. If neither
is provided, the server uses the MCP process current working directory. All
relative tool paths are resolved from this workspace root.
Claude Code using PyPI:
claude mcp add jons-mcp-java \
-- uvx jons-mcp-java /path/to/java-workspaceClaude Code using a source checkout:
claude mcp add jons-mcp-java \
-- uv run --project /path/to/jons-mcp-java \
jons-mcp-java /path/to/java-workspaceClaude Code using GitHub:
claude mcp add jons-mcp-java \
-- uvx --from git+https://github.com/jonmmease/jons-mcp-java.git \
jons-mcp-java /path/to/java-workspaceCodex CLI using PyPI:
codex mcp add jons-mcp-java \
-- uvx jons-mcp-java /path/to/java-workspaceCodex CLI using GitHub:
codex mcp add jons-mcp-java \
-- uvx --from git+https://github.com/jonmmease/jons-mcp-java.git \
jons-mcp-java /path/to/java-workspace.mcp.json:
{
"mcpServers": {
"jons-mcp-java": {
"command": "uvx",
"args": [
"jons-mcp-java",
"/path/to/java-workspace"
]
}
}
}Codex TOML:
[mcp_servers.jons-mcp-java]
command = "uvx"
args = [
"jons-mcp-java",
"/path/to/java-workspace",
]The configured workspace root is the filesystem security boundary.
Tool paths may be workspace-relative paths, absolute in-workspace paths, or
file:// URIs.
Relative paths are resolved from the configured workspace root, not from the MCP server process cwd.
Paths containing .., paths outside the workspace, non-file URIs, malformed
URIs, missing files, and symlink escapes are rejected before any filesystem or
JDT.LS access.
LSP locations outside the workspace may still be returned with
"inWorkspace": false, but the server does not open or read external files.
Path and startup failures use a stable error shape:
{
"status": "error",
"error": {
"type": "path_outside_workspace",
"message": "Path resolves outside the configured workspace root.",
"path": "../outside.java"
}
}Tool | Description |
| Go to symbol definition |
| Find all references to a symbol |
| Find implementations of interfaces/abstract methods |
| Go to type definition |
| List symbols in a file |
| Search symbols in an initialized project |
| Get fresh diagnostics for one file |
| Get hover-style Javadoc and type information |
| Preview symbol rename edits without writing files |
| Stop one or all JDT.LS clients and clear runtime state |
The first file-backed call for a project starts JDT.LS lazily and usually returns:
{
"status": "initializing",
"message": "Starting project initialization; please retry shortly.",
"project": "/path/to/java-workspace/app"
}Retry the same tool after initialization finishes.
Tools that accept or return line and character use one-based positions,
matching editor and agent Read output. If your editor shows line 28, pass
line=28; returned ranges use the same convention. Use document_symbols to
discover one-based symbol ranges when you do not already know a position.
Successful navigation tools return normalized items:
{
"items": [
{
"uri": "file:///path/to/Main.java",
"range": {
"start": { "line": 12, "character": 8 },
"end": { "line": 12, "character": 12 }
},
"inWorkspace": true
}
],
"totalItems": 1
}references, document_symbols, workspace_symbols, and diagnostics return
paginated results with items, totalItems, offset, limit, hasMore, and
nextOffset.
Navigation tools preserve JDT.LS result order and return items plus
totalItems. references, diagnostics, and symbol lists are sorted
deterministically before pagination.
preview_rename is safe to inspect. It returns a flat list of file URI,
one-based replacement range, newText, and inWorkspace values, plus
totalEdits. It does not write to disk.
The server tracks open LSP documents and compares disk metadata plus content
hashes before read-style tool calls. If a file changed outside JDT.LS, the
server sends a full-document didChange and didSave before requesting fresh
language data.
diagnostics is file-scoped and always refreshes the target file before
returning compiler diagnostics.
Use restart_server only as a fallback:
{ "file_path": "app/src/main/java/example/Main.java" }With no file_path, restart_server stops all active JDT.LS clients. Servers
restart lazily on the next file-backed tool call.
JDT.LS not found: install JDT.LS, put jdtls on PATH, or set JDTLS_HOME.
Java 21+ required: install Java 21+ or set JAVA_HOME.
project_not_found: the file is inside the workspace, but not under a
discovered Gradle root.
path_outside_workspace: the path resolves outside
the configured workspace root.
project_startup_failed: the project import failed; check the JDT.LS stderr
log under the generated workspace data directory in ~/.cache/jdtls-workspaces.
Read-only JDTLS_HOME: set JDTLS_CONFIG_DIR to a writable directory, or let
the server create and permission-repair its cached config copy automatically.
Navigate to the definition of a symbol at the given position.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| line | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only says 'navigate to definition' without detailing what the tool returns, error handling, or side effects. The output schema exists but is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the key action. However, it may be too brief, missing important context that could be included without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the availability of an output schema and sibling tools, the description is incomplete. It does not explain return behavior (e.g., location details) or parameter semantics, making it insufficient for reliable tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds no meaning to the parameters file_path, line, and character. It does not specify coordinate indexing (0-based vs 1-based) or the meaning of position relative to file content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (navigate to definition) and the target (symbol at given position). It uses a specific verb and resource, and the context of sibling tools like implementation and type_definition helps distinguish it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like references or implementation. Sibling tools are listed but no conditional logic or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get fresh diagnostics for one Java file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully cover behavioral traits. It only implies real-time fetching with 'fresh', but does not disclose side effects, auth requirements, or rate limits. This is insufficient for a mutation-free diagnostic tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structured details. It is not verbose, but the brevity sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return value documentation is not needed. However, the description fails to explain the tool's context within the sibling set, nor does it cover the significance of limit/offset parameters. The tool is part of a language server, but that context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. Despite the schema having defaults for limit and offset, their meaning and usage are omitted. The description adds no value over the bare schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'fresh diagnostics for one Java file', which clearly indicates the tool's purpose. However, it does not differentiate from sibling tools like 'definition' or 'references', so it loses some points.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites or exclusion criteria, leaving the agent without context for optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all symbols defined in a Java file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior, but it only states the basic operation. It does not mention pagination behavior (limit/offset), file requirements, or output characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and concise, but it is too brief given the tool's complexity, lacking detail that would justify its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return values are covered, but the description omits important context such as symbol types, pagination behavior, and file prerequisites, making it incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description should compensate. It does not explain 'file_path', 'limit', or 'offset', leaving the agent to infer from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves symbols defined in a Java file, using a specific verb and resource. However, it does not distinguish from sibling tools like 'workspace_symbols' which cover a broader scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'workspace_symbols', 'symbol_info'). There is no mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find implementations of an interface or abstract method.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| line | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It does not disclose whether it returns direct or all descendants, works across files, or any limitations. The existence of an output schema is noted but its content is unknown, leaving behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence that front-loads the core action. No extraneous words; every part is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero annotations, no parameter descriptions, and no usage guidance, the description is incomplete for a tool likely requiring nuances (e.g., scope of search, return format). The output schema exists but is not described, leaving agents without full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description adds no parameter context beyond names. However, the parameter names (file_path, line, character) are self-explanatory for a location-based tool, so it does not detract significantly. Baseline 3 is appropriate as schema does not fully compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find implementations of an interface or abstract method', specifying the verb 'Find', the resource 'implementations', and the context (interface or abstract method). This distinguishes it from sibling tools like 'definition' (go to declaration) and 'type_definition' (type definition).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like 'references' or 'definition'. The use case is implied but not elaborated, and there are no when-not-to-use hints or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview a symbol rename across the project without writing files.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| line | Yes | ||
| character | Yes | ||
| new_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'without writing files', indicating non-destructive behavior, but lacks details on output format, error handling, or any other behavioral traits. With no annotations provided, the description should cover more.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff; efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 required parameters and an output schema, the description is too minimal. It doesn't explain what the preview returns (e.g., list of changes, conflicts), leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and no parameter explanations are provided in the description. While parameter names are self-explanatory, the description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'preview' with resource 'symbol rename' and scope 'across the project', distinguishing it from any sibling tools that might perform actual renames.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no examples, and no mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all references to the symbol at the given position.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| line | Yes | ||
| character | Yes | ||
| include_declaration | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It does not mention pagination via limit/offset, the effect of include_declaration, or any performance characteristics. The minimal description leaves many behavioral aspects undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded with the core purpose. However, it could be slightly more structured by listing key parameters or use cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and moderate complexity (6 parameters, paging), the description is too sparse. It does not explain paging or the inclusion of declarations. An output schema exists, so return values need not be detailed, but behavioral completeness is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the parameters. With 6 parameters (3 required), the description should clarify their roles, but it only references the symbol position implicitly. This is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'find' and resource 'references', and specifies that it operates on a symbol at a given position (file_path, line, character). This distinguishes it from sibling tools like 'definition' and 'type_definition'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives such as 'definition', 'implementation', or 'type_definition'. The description lacks any context for appropriate usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop JDT.LS server(s) and clear runtime state.
Servers restart lazily on the next file-backed tool call.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden; it discloses lazy restart behavior and state clearing, though does not detail potential side effects or destructive actions beyond clearing runtime state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant information; effective front-loading of key action and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core functionality and behavior adequately for a simple reset tool, though missing parameter details and more comprehensive behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'file_path' has 0% schema description coverage and no mention in the description, leaving its purpose and usage ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly defines verb 'Stop' and resource 'JDT.LS server(s)', mentions clearing runtime state, and is distinct from sibling tools which are file/symbol-based operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States that servers restart lazily on next file-backed tool call, implying when it takes effect, but does not explicitly mention when to use or avoid using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get hover information for a symbol at the given position.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| line | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry behavioral disclosure. It only implies read-only via 'Get', but lacks details on performance, side effects, or 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence with no extraneous content. Every word serves the purpose of explaining the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the existence of an output schema, the description is still insufficient: it provides no usage context nor parameter details. The agent would lack guidance on when to use symbol_info vs definition or references.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 required parameters with 0% description coverage in the schema. The description adds no semantic meaning to the parameters; it only generically references 'the given position'. No parameter formats or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'hover information' with the precise scope 'at a given position'. This distinguishes it from sibling tools like 'definition' or 'references', which return different symbol information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only states function, not context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Navigate to the type definition of a symbol at the given position.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| line | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It does not mention what happens if the symbol has no type definition, whether the operation is read-only, or any side effects. The description is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is concise and front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three required parameters and no annotations, the description is too brief. It does not explain the return value (though output schema exists) or edge cases, making it incomplete for an agent to use reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds no information about the parameters. It does not explain what each parameter means (e.g., file_path, line, character) or how they relate to the symbol position.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Navigate to the type definition') and the target (a symbol at a given position). It distinguishes itself from the sibling tool 'definition' by specifying 'type definition'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'definition', or any prerequisites or context. The description is purely functional with no usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for symbols in an initialized project workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| file_path | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only mentions 'initialized project workspace' without defining initialization or explaining if the operation is read-only, returns multiple results, or any other effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, which is concise, but it is too brief to be useful. It does not earn its place well because it omits essential details that could be added in the same length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 4 parameters and an output schema, the description gives no context about how the search works, what symbols are returned, or how the parameters affect the results. It is completely inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema parameter descriptions coverage is 0%, yet the description adds no information about the parameters (query, file_path, limit, offset). The description completely fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool searches for symbols in a workspace, which is clear in basic function. However, it does not differentiate itself from sibling tools like document_symbols, which also search symbols but within a document, missing a chance to clarify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like symbol_info or document_symbols. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct operation (e.g., definition, references, diagnostics). The slight overlap between definition and type_definition is clarified by their descriptions, and all tools have clear boundaries.
All tool names follow a consistent lowercase_snake_case pattern using descriptive nouns (e.g., definition, references) or verb_actions (preview_rename). No mixing of conventions.
10 tools is well within the ideal range for a focused Java language server. Each tool serves a distinct purpose without unnecessary bloat or deficiency.
Covers navigation, search, diagnostics, and rename preview. Missing an actual rename apply tool and code completion, but the core workflow for symbol analysis is well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ship better Java with your coding agent.
Lean 4 MCP server: compile, prove theorems, and formalize math with Mathlib.
The official Svelte MCP server providing docs and autofixing tools for Svelte development
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jonmmease/jons-mcp-java'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
