The server provides 8 specialized Java diagnostic tools with clear action-verb naming and reasonable schema coverage. However, tool descriptions are terse (averaging ~70 chars), parameter descriptions are minimal or absent, output schemas are not documented in the definitions, and error handling lacks recovery guidance. The tool set is focused and well-named (e.g., java_list_processes, java_heap_dump), but the definitions fall short of LLM-optimization standards. No tool annotations (readOnlyHint/destructiveHint) are present despite clear risk classifications. Per-tool schemas are JSON Schema typed but lack parameter descriptions beyond bare type information.
Parameter descriptions are missing or minimal. Only type information is provided; no guidance on valid ranges, formats, or constraints. E.g., 'pid' parameter lacks explanation of how to obtain a PID or what happens if invalid. 'interval_s' and 'samples' have defaults but no min/max bounds documented.
Output schemas are not documented. Tools.py returns structured dicts with 'evidence', 'metrics', 'confidence', 'next_recommended_action' fields, but these are not declared in tool definitions. LLMs cannot plan downstream calls without knowing what fields to expect.
Add detailed parameter descriptions to all tools. For numeric params (pid, interval_s, samples, duration_s), document valid ranges and defaults. E.g., 'pid (integer, required): The process ID of the target JVM. Obtain via java_list_processes if unknown. Must be a running JVM owned by the same OS user.'
Document output schemas in tool definitions. Specify the structure of returned 'metrics', 'evidence', 'confidence', and 'next_recommended_action' fields. Example: 'Returns {evidence: [string], metrics: {process_count: int, processes: [{pid: int, main_class: string, ...}]}, confidence: string, next_recommended_action: string}'
Add tool annotations to the MCP server registration: mark java_list_processes, java_gc_snapshot, java_class_histogram, java_jfr_summary, java_mat_suspects as readOnlyHint=true. Mark java_jfr_start, java_heap_dump, java_async_alloc_profile as destructiveHint=true. This enables agents to distinguish safe read operations from state-changing calls.
Expand tool descriptions to 100-150 characters with intent guidance. Example for java_gc_snapshot: 'Collect garbage collection utilization trends for a JVM process over time. Use this after java_list_processes to detect GC pressure (high OldGen utilization or frequent Full GC) that indicates possible memory leaks. Requires jstat (OpenJDK 17+).'
Implement error classification in error responses. Return a 'error_type' field (e.g., 'missing_tool', 'invalid_pid', 'permission_denied', 'timeout') and recovery guidance specific to the error. Example: 'error_type: missing_tool, next_action: Install OpenJDK 17+ so jstat is available, or set JAVA_HOME if jstat is already installed.'
Score history
Overall score trend
First recorded score · v2 rubric
55/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-23
D
55
2026-07-28+
v2
java_mat_suspectsread onlysource verified68/100
Run Eclipse Memory Analyzer (MAT) on a heap dump to identify memory leak suspects
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Risk classifications exist in metadata ('READ_ONLY' vs 'WRITE') but are not exposed in the MCP tool definitions. Agents cannot distinguish safe vs unsafe tools without reading risk hints.
Error handling provides minimal recovery guidance. Functions like _command_failed() return generic error messages with a single next_recommended_action. No distinction between retryable (e.g., timeout), user-fixable (e.g., invalid PID), or fatal errors. No categorization to guide agent decision logic.
Tool descriptions are below 100 characters and lack context. 'Capture garbage collection utilization snapshot for a JVM process using jstat' (73 chars) does not explain WHEN to call this tool vs alternatives, what prerequisites exist (e.g., jstat must be installed), or how results should be interpreted. Descriptions should be 50-200 chars and include intent guidance.
No pagination or result-limit enforcement documented. java_list_processes returns all processes. If a system has hundreds of JVMs, the response could be very large. No documented limit, page size parameter, or guidance on capping output.
java_list_processes
Add confirmation/dry-run support for destructive tools (java_jfr_start, java_heap_dump, java_async_alloc_profile). If these tools are called without explicit confirmation, return a result with 'input_required' status asking the user to confirm the operation.
Document default parameter behavior. For java_jfr_start, clarify that out_file defaults to a system temp directory with a timestamp suffix. For java_heap_dump, explain that live_only=true excludes unreachable objects. This prevents silent misunderstandings about what data is collected.
Add validation and constraints to parameters. E.g., interval_s should be >= 1, samples should be >= 2, duration_s should be 1-300. Validation errors should return the constraint violation, not a generic failure. Example: 'Invalid samples: 1. Must be >= 2 to collect meaningful GC trends.'
Consider adding a helper tool or documentation on how to resolve common errors: AttachNotSupportedException (ensure target JVM is owned by the same OS user), missing binaries (set JAVA_HOME or install tools), and permission errors (run with elevated privileges if necessary).