What can you do with this server?

JavaLens MCP server provides 63 semantic analysis tools for Java codebases, built on Eclipse JDT for compiler-accurate code understanding, navigation, refactoring, and metrics. Project Management: Load Maven, Gradle, Bazel, or plain Java projects; check server health; inspect project structure, classpath, and type members. Navigation & Search: Search symbols by glob pattern; go to definitions; find references, implementations, and type hierarchies; list file symbols; get symbol/type/method/field info at a position; find super methods. Fine-Grained Reference Search (JDT-unique, beyond standard LSP): * Annotation usages, type instantiations (new Type()), casts ((Type) expr), instanceof checks * throws declarations, catch blocks, method references (Type::method), generic type arguments (List ), and Java reflection usage Code Analysis: Get diagnostics (errors/warnings); validate syntax; trace incoming/outgoing call hierarchies; find field writes; discover JUnit/TestNG tests; detect unused private members and potential bugs (null risks, resource leaks, empty catches); get hover info, Javadoc, signature help, and enclosing element; analyze change impact (blast radius), data flow, and control flow; find Spring DI registrations. Compound Analysis (reduces round-trips): analyze_file, analyze_type, analyze_method, get_type_usage_summary — each aggregates multiple analyses in a single call. Refactoring (returns text edits, does not modify files directly): Rename symbols project-wide; organize imports; extract variable/method/constant/interface; inline variable/method; change method signature; convert anonymous class to lambda. Quick Fixes: Suggest imports for unresolved types; list available quick fixes at a position; apply fixes (add/remove import, add throws, surround with try-catch). Metrics & Code Quality: Cyclomatic/cognitive complexity; package/type dependency graphs; circular dependency detection (Tarjan's SCC); find large classes; check Java naming convention violations.

Which integrations are available for this server?

Provides compiler-accurate Java code analysis using Eclipse JDT Core, enabling semantic understanding of Java codebases including type resolution, method overloading, inheritance hierarchies, and fine-grained reference analysis. Enables detection of Spring Dependency Injection registrations and annotations (@Component, @Bean, @Autowired, @Inject) for analyzing Spring-based Java applications.

de en es ja ko ru zh

javalens-mcp

by pzalutski-pixel

Overview Schema Source Related Servers Discussions Admin

Local

JavaLens: AI-First Code Analysis for Java

An MCP server providing 75 semantic analysis tools for Java, built directly on Eclipse JDT for compiler-accurate code understanding.

Built for AI Agents

JavaLens exists because AI systems need compiler-accurate insights that reading source files cannot provide. When an AI uses grep or Read to find usages of a method, it cannot distinguish:

A method call from a method with the same name in an unrelated class
A field read from a field write
An interface implementation from an unrelated class
A cast to a type from other references to that type

This leads to incorrect refactorings, missed usages, and incomplete understanding of code behavior.

Related MCP server: java-jdtls-mcp-server

Compiler-Accurate Analysis

JavaLens provides compiler-accurate code analysis through Eclipse JDT—the same engine that powers Eclipse IDE. Unlike text search, JDT understands:

Type resolution across inheritance hierarchies
Method overloading and overriding
Generic type arguments
Import resolution and classpath dependencies
Java source from version 1.1 through Java 25 (markdown Javadoc, module imports, compact source files, flexible constructor bodies)
Lombok-generated members — a bundled agent makes @Data accessors and the like resolve, so code using them is not flagged as undefined

Example: Finding all places where UserService.save() is called:

Approach	Result
`grep "save("`	Returns 47 matches including `orderService.save()`, `saveButton`, comments
`find_references`	Returns exactly 12 calls to `UserService.save()`

AI Training Bias Warning

⚠️ Important for AI developers and users

AI models may exhibit trained bias toward native tools (Grep, Read, LSP) over MCP server tools, even when semantic analysis provides better results. This happens because:

Training data contains extensive grep/text-search patterns
Native tools are "always available" in the model's experience
The model may not recognize when semantic analysis is superior

To get the best results:

Add guidance to your project instructions or system prompt (e.g., CLAUDE.md for Claude Code):

## Code Analysis Preferences

For Java code analysis, prefer JavaLens MCP tools over text search:
- Use `find_references` instead of grep for finding usages
- Use `find_implementations` instead of text search for implementations
- Use `analyze_type` to understand a class before modifying it
- Use refactoring tools (rename_symbol, extract_method) for safe changes

Semantic analysis from JDT is more accurate than text-based search,
especially for overloaded methods, inheritance, and generic types.

What is JavaLens?

JavaLens is an MCP server that gives AI assistants deep understanding of Java codebases. It provides semantic analysis, navigation, refactoring, and code intelligence tools that go beyond simple text search.

Why Not LSP?

Language Server Protocol was designed for IDE autocomplete and basic navigation—not for AI agent workflows that require deep semantic analysis.

Capability	Native LSP	JavaLens
Find all `@Annotation` usages	❌	✅
Find all `new Type()` instantiations	❌	✅
Find all casts to a type	❌	✅
Distinguish field reads from writes	❌	✅
Detect circular package dependencies	❌	✅
Calculate cyclomatic complexity	❌	✅
Find unused private methods	❌	✅
Detect possible null pointer bugs	❌	✅
Project-wide dead-code reachability from entry points	❌	✅
Find the tests that exercise a symbol, transitively	❌	✅

JavaLens wraps Eclipse JDT Core directly via OSGi, providing:

Fine-grained reference types: Find specifically casts, annotations, throws clauses, catch blocks, instanceof checks, method references, type arguments
Read vs write access distinction: Track where fields are mutated vs just read
Indexed search: JDT pre-builds an index at load time, so symbol/reference queries do not walk source files
Full AST access: Direct manipulation for complex refactorings

Installation

Prerequisites

Java 21 or later (must be on PATH or set JAVA_HOME) — required for both install paths.
Node.js 18+ — required only if you use the npm/npx install path below. Skip if you use the direct-download path.

JavaLens is an analytical server, not a compiler. It uses Eclipse JDT 2025-12 to parse and understand Java source code from version 1.1 through 25. Java 21 is required only as the server runtime.

Install from GitHub Releases (recommended — Java only)

This is the simplest path if you already have Java 21 and don't have Node.js. Download from Releases:

Platform	File
All platforms	`javalens.zip` or `javalens.tar.gz`

Extract to a location of your choice (e.g., /opt/javalens or C:\javalens). Then point your MCP client at the bundled jar — see Configure MCP Client below.

Install via npm (requires Node.js 18+)

If you already have Node.js, npx will download and cache the JavaLens distribution (~23 MB) on first run:

{
  "mcpServers": {
    "javalens": {
      "command": "npx",
      "args": ["-y", "javalens-mcp"],
      "env": {
        "JAVA_PROJECT_PATH": "/path/to/your/java/project"
      }
    }
  }
}

Configure MCP Client

Add to your MCP configuration (e.g., .mcp.json for Claude Code):

{
  "mcpServers": {
    "javalens": {
      "command": "java",
      "args": ["-jar", "/path/to/javalens/javalens.jar", "-data", "/path/to/javalens-workspaces"]
    }
  }
}

The -data argument specifies where JavaLens stores its workspace metadata. See How Workspaces Work below.

Auto-Load a Project

Set JAVA_PROJECT_PATH to auto-load a project when the server starts:

{
  "mcpServers": {
    "javalens": {
      "command": "java",
      "args": ["-jar", "/path/to/javalens/javalens.jar", "-data", "/path/to/javalens-workspaces"],
      "env": {
        "JAVA_PROJECT_PATH": "/path/to/your/java/project"
      }
    }
  }
}

Note: Project loading happens asynchronously in the background. The MCP server responds immediately while the project loads. Use health_check to monitor loading status—it will show "project.status": "loading" until complete, then "loaded" when ready.

How Workspaces Work

Unlike in-memory code models, Eclipse JDT requires a workspace directory to store:

Search indexes for fast symbol lookup
Compilation state and caches
Project metadata

Workspaces Are Outside Your Source

JavaLens creates its workspace outside your source project to keep your codebase clean:

Your Java Project (unchanged)
├── src/main/java/
├── pom.xml
└── (no Eclipse files added)

JavaLens Workspace (specified by -data)
└── {session-uuid}/
    ├── .metadata/          <- JDT indexes and state
    └── javalens-project/   <- Links to your source (not copies)

Why this matters:

No pollution: Your source tree stays clean—no .project or .classpath files
No conflicts: Works alongside any build system without interference
Session isolation: Each MCP session gets its own workspace, enabling concurrent analysis

Session Lifecycle

JavaLens starts and creates a unique workspace: {base}/{uuid}/
load_project creates linked folders pointing to your source
JDT builds indexes in the workspace (not in your project)
When the session ends, the workspace is cleaned up

Tools

Tool	Description
`search_symbols`	Search types, methods, fields by glob pattern
`go_to_definition`	Navigate to symbol definition
`find_references`	Find all usages of a symbol
`find_implementations`	Find interface/class implementations
`get_type_hierarchy`	Get inheritance chain
`get_document_symbols`	Get all symbols in a file
`get_symbol_info`	Get detailed symbol information at position
`get_type_at_position`	Get type details at cursor
`get_method_at_position`	Get method details at cursor
`get_field_at_position`	Get field details at cursor

Fine-Grained Reference Search (9 tools)

These use JDT's unique reference type constants—not available through LSP:

Tool	Description
`find_annotation_usages`	Find all `@Annotation` usages
`find_type_instantiations`	Find all `new Type()` calls
`find_casts`	Find all `(Type) expr` casts
`find_instanceof_checks`	Find all `x instanceof Type`
`find_throws_declarations`	Find all `throws Exception` in signatures
`find_catch_blocks`	Find all `catch(Exception e)` blocks
`find_method_references`	Find all `Type::method` expressions
`find_type_arguments`	Find all `List<Type>` usages
`find_reflection_usage`	Find `Class.forName()`, `Method.invoke()`, and other reflection calls

Analysis (20 tools)

Tool	Description
`get_diagnostics`	Get compilation errors and warnings
`validate_syntax`	Fast syntax-only validation
`get_call_hierarchy_incoming`	Find all callers of a method
`get_call_hierarchy_outgoing`	Find all methods called by a method
`find_field_writes`	Find where fields are mutated
`find_tests`	Discover JUnit/TestNG test methods
`find_unused_code`	Find unused private members
`find_unreachable_code`	Project-wide dead code — members unreachable from any main method or test, over the whole-program call graph
`find_affected_tests`	The tests that exercise a symbol, directly or transitively — the set to run after changing it
`find_possible_bugs`	Detect null risks, empty catches, resource leaks
`get_hover_info`	Get documentation/signature for symbol
`get_javadoc`	Get parsed Javadoc
`get_signature_help`	Get method signature at call site
`get_enclosing_element`	Get containing method/class at position
`analyze_change_impact`	Blast radius — direct call sites by depth, or the full transitive closure over the project graph (`transitive=true`)
`analyze_data_flow`	Variable read/write/declaration tracking within a method; opt-in `followCalls` tracks null/taint facts across calls to sinks
`analyze_control_flow`	Branching, loops, return/throw points, nesting depth
`get_di_registrations`	Find Spring DI registrations (@Component, @Bean, @Autowired, @Inject)
`get_jpa_model`	Assembled JPA entity model — tables, id fields, relationships with resolved targets and mappedBy sides
`get_http_endpoints`	Assembled HTTP route table — Spring and JAX-RS paths composed from class prefixes, mapped to handler methods

Compound Analysis (4 tools)

Combine multiple queries to reduce round-trips:

Tool	Description
`analyze_file`	Get imports, types, diagnostics in one call
`analyze_type`	Get members, hierarchy, usages, diagnostics
`analyze_method`	Get signature, callers, callees, overrides
`get_type_usage_summary`	Get instantiations, casts, instanceof counts

Refactoring (16 tools)

All refactoring tools return text edits (and new-file content where a refactoring creates one) rather than applying changes directly:

Tool	Description
`rename_symbol`	Rename across entire project
`organize_imports`	Sort and clean imports
`extract_variable`	Extract expression to local variable
`extract_method`	Extract code block to new method
`extract_constant`	Extract to `static final` field
`extract_interface`	Create interface from class methods
`extract_superclass`	Move a member into a newly created superclass
`inline_variable`	Replace variable with its initializer
`inline_method`	Replace call with method body
`change_method_signature`	Modify params/return, update all callers
`convert_anonymous_to_lambda`	Convert anonymous class to lambda
`encapsulate_field`	Generate accessors and rewrite all direct field accesses
`pull_up`	Move a member into the superclass
`push_down`	Move a member into the subclasses
`introduce_parameter_object`	Bundle a method's parameters into a new class, updating callers
`move_type_to_new_file`	Move a nested type into its own top-level file

Quick Fixes (5 tools)

Tool	Description
`suggest_imports`	Find import candidates for unresolved type
`get_quick_fixes`	List available fixes for problem at position
`apply_quick_fix`	Apply fix by ID (add import, remove import, add throws, try-catch)
`apply_cleanup`	Apply one of 10 JDT clean-ups (convert loops, pattern matching, switch expressions, text blocks, ...) and return rewritten source
`diagnose_and_fix`	Diagnose a file and return each problem's top quick-fix edits in one call

Metrics (5 tools)

Tool	Description
`get_complexity_metrics`	Cyclomatic/cognitive complexity, LOC per method
`get_dependency_graph`	Package/type dependencies as nodes and edges
`find_circular_dependencies`	Detect package cycles using Tarjan's SCC algorithm
`find_large_classes`	Find types exceeding method/field/line count thresholds
`find_naming_violations`	Check against Java naming conventions

Project & Infrastructure (6 tools)

Tool	Description
`health_check`	Server status and capabilities
`load_project`	Load Maven/Gradle/Bazel/plain Java project
`get_project_structure`	Get package hierarchy
`get_classpath_info`	Get classpath entries
`get_type_members`	Get members by type name
`get_super_method`	Find overridden method in superclass

Usage

Basic Workflow

1. load_project(projectPath="/path/to/java/project")
2. search_symbols(query="*Service", kind="Class")
3. find_references(filePath="...", line=10, column=15)
4. analyze_type(typeName="com.example.UserService")

Coordinate System

All line/column parameters are zero-based:

Line 0, Column 0 = first character of file

Path Handling

Response paths are relative by default
All paths use forward slashes for cross-platform consistency
Input paths can be relative or absolute

Important Notes

Disk Synchronization

Every answer is verified against the files on disk at query time. Before any tool logic runs, JavaLens content-hashes the known source files, detects edits, additions, and deletions (the agent reports nothing — the server discovers changes itself), repairs exactly what changed, waits for the search index to absorb the repair, and only then answers. There is no file watcher and no background thread — verification is synchronous inside the query the agent issued, so there are no race conditions.

The agent's loop is just: edit → query.

1. Use JavaLens tools to analyze
2. Write changes to files
3. Use JavaLens tools to verify — answers already reflect the changes

load_project is needed only on first use, when a response reports RELOAD_REQUIRED (a build file like pom.xml changed, so the classpath must be rebuilt), or to rebuild everything from scratch. If verification itself fails, the query returns VERIFICATION_FAILED rather than an unverified answer.

Cost: verification is hash-based and parallel — measured per query at ~2 ms for a 72-file project, ~25 ms at 1,000 files, ~180 ms at 10,000 files. Repairs cost only what changed (one edited file reconciles in well under a second), never a full reindex.

Manual mode: set JAVALENS_DISK_SYNC=manual to restore the pre-1.5.0 contract — answers reflect the last load and the agent calls load_project after editing files. Tool descriptions and the MCP instructions field always state the active contract, and health_check reports it as diskSync.

Refactoring Returns Edits

Refactoring tools return text edits but don't modify files. This gives visibility into what would change before applying.

Session Isolation

Each MCP session is independent with its own workspace UUID. Multiple sessions can analyze the same project concurrently.

Build System Support

JavaLens loads three real build systems plus plain Java directories. Each is exercised end-to-end in CI against synthetic real-shaped fixtures (multi-module reactors with cross-module deps, real external libraries, annotation processors).

System	Detection	Single-module	Multi-module / multi-project	Compiler compliance from build files	Generated sources	Annotation processors
Maven	`pom.xml`	✅	✅ (reactor classpath aggregation, cross-module navigation)	✅ (`maven.compiler.release`/`source`/`target`)	✅ (`target/generated-sources/*`)	✅ (`<annotationProcessorPaths>` across the whole reactor)
Gradle	`build.gradle` / `build.gradle.kts`	✅	✅ (`settings.gradle include` parsed; per-subproject classpaths unioned)	✅ (`sourceCompatibility`)	✅ (`build/generated/sources/<task>/main/java`)	✅ (`annotationProcessor` configuration)
Bazel	`MODULE.bazel` / `WORKSPACE.bazel` / `WORKSPACE`	✅	✅ (every `BUILD.bazel` package scanned for sources; `bazel-bin` ↔ `bazel-out` symlink dedup)	✅ (`javacopts` `-source`/`-target`/`--release` parsed across `BUILD.bazel` files)	n/a (Bazel actions write into `bazel-bin/`, not `target/generated-sources/`)	✅ (any classpath jar with `META-INF/services/javax.annotation.processing.Processor` is auto-registered)
Plain Java	`src/` directory	✅	n/a	✅ (falls back to `Runtime.version().feature()` when no build file)	n/a	n/a

Subprocess invocations of mvn / gradle happen during project load. If a tool is missing or fails, JavaLens surfaces a structured LoadWarning (e.g. MAVEN_SUBPROCESS_FAILED, GRADLE_SUBPROCESS_FAILED, COMPLIANCE_LEVEL_UNKNOWN) in the load_project response so callers know analysis quality is degraded rather than silently getting an empty classpath.

Configuration

Environment Variable	Description	Default
`JAVA_PROJECT_PATH`	Auto-load project on startup	(none)
`JAVALENS_TIMEOUT_SECONDS`	Operation timeout	30
`JAVALENS_DISK_SYNC`	`strict` (every answer verified against disk) or `manual` (agent calls `load_project` after edits)	strict
`JAVALENS_LOG_LEVEL`	TRACE/DEBUG/INFO/WARN/ERROR	INFO
`JAVA_TOOL_OPTIONS`	JVM options, e.g. `-Xmx2g` for large projects	(default: 512m via eclipse.ini)
`JAVALENS_LOMBOK_JAR`	Path to the Lombok agent jar attached at launch; overrides the bundled one	(bundled)

Building from Source

git clone https://github.com/pzalutski-pixel/javalens-mcp.git
cd javalens-mcp
./mvnw clean verify

Distributions are output to org.javalens.product/target/products/.

Build Requirements

Java 21+ (server runtime)
Maven 3.9+ (wrapper included as ./mvnw)

To run the full test suite (which includes end-to-end tests against real Maven, Gradle, and Bazel builds), the corresponding tools must also be on PATH:

Maven (provided by the wrapper)
Gradle 8+
Bazel 9+ (or bazelisk)

Tests gracefully skip when a tool is missing on a developer machine. Set JAVALENS_TESTS_REQUIRE_TOOLS=true to flip the gate: missing tools cause a hard failure instead of a skip. CI runs with this flag set so any provisioning gap surfaces as a real failure rather than weakening the suite silently.

Testing

# Full suite, gentle (missing tools skip)
./mvnw verify

# Full suite, strict (missing tools fail; what CI does)
JAVALENS_TESTS_REQUIRE_TOOLS=true ./mvnw verify

Build-system coverage is structured as focused per-bug tests plus realistic end-to-end tests. The end-to-end tests load a single representative project per build system that exercises every fix in one pass — multi-module Maven with Lombok APT and cross-module references; multi-project Gradle with annotation processors; multi-target Bazel with cross-target deps. CI runs them on Linux, macOS, and Windows.

Architecture

flowchart TD
    Client["<b>MCP Client</b>"]
    MCP["<b>org.javalens.mcp</b><br/>McpProtocolHandler → ToolRegistry → 75 Tools"]
    Core["<b>org.javalens.core</b><br/>JdtServiceImpl → WorkspaceManager, SearchService"]
    JDT["<b>Eclipse JDT Core</b> (via OSGi / Equinox)<br/>IWorkspace, IJavaProject, SearchEngine, ASTParser"]

    Client -->|"JSON-RPC over stdio"| MCP
    MCP --> Core
    Core --> JDT

License

MIT License - see LICENSE for details.

Available Tools

75 tools

analyze_change_impactA

Analyze the blast radius of changing a symbol.

USAGE: analyze_change_impact(filePath="path/to/File.java", line=10, column=5) OUTPUT: All files and call sites affected, grouped by file

Options:

depth: How many levels of callers to follow (default 1, max 3) depth=1: direct references only depth=2: references + callers of those references depth=3: three levels deep
transitive: full reverse closure over the project call graph (default false). No depth ceiling; follows calls, instantiations, field accesses, and override declarations (callers through an interface or superclass count). Returns affectedMethods + affectedFiles instead of callSites. Supports project methods, fields, and types.
maxResults: cap on affectedMethods in transitive mode (default 200)

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	File containing the symbol
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number
`depth`	No	Levels of transitive callers to follow (default 1, max 3)
`transitive`	No	Full reverse closure over the project graph, no depth ceiling (default false)
`maxResults`	No	Cap on affectedMethods in transitive mode (default 200)

TDQS

A4.6/5.0

Behavior5/5

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

No annotations are provided, so the description carries full responsibility. It discloses direct and transitive mode behaviors, depth limits, maxResults cap, supported symbol types, and output format changes between modes. This is comprehensive and transparent.

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

Conciseness4/5

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

The description is well-structured with a purpose statement, usage example, output description, and bulleted options. While slightly lengthy, every section provides necessary information, and the front-loading helps quick understanding.

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 tool's complexity (6 parameters, no output schema), the description explains output formats and main behaviors. It covers both depth and transitive modes. Minor missing details like error handling or edge cases, but overall adequate for selection and invocation.

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

Parameters5/5

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

The input schema covers all 6 parameters with 100% description coverage. The tool's description adds significant value beyond the schema by explaining default values, mode behaviors, and the meaning of depth levels, enabling correct parameter usage.

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 purpose: 'Analyze the blast radius of changing a symbol.' It includes a usage example, output description, and detailed options. The tool's name and description differentiate it from siblings like 'find_references' and 'get_call_hierarchy_incoming' by focusing on impact analysis.

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 a usage example, parameter explanations, and the prerequisite 'Requires load_project to be called first.' It lacks explicit guidance on when not to use this tool versus alternatives, but the behavioral details (e.g., transitive vs depth) help infer appropriate contexts.

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

analyze_control_flowB

Analyze the control flow structure of a method.

USAGE: analyze_control_flow(filePath="path/to/File.java", line=10, column=5) OUTPUT: Branching points, loops, returns, throws, and nesting depth

Reports:

Branch count (if/switch/ternary)
Loop count and types (for/while/do-while/enhanced-for)
Return points with line numbers
Throw points with exception types and line numbers
Try-catch blocks with caught exception types
Maximum nesting depth

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	File containing the method
`line`	Yes	Zero-based line number within the method
`column`	Yes	Zero-based column number

TDQS

B3.4/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 the full burden of behavioral disclosure. It does not explicitly state that the tool is read-only or have side effects, nor does it discuss performance or permissions. The word 'Analyze' implies inspection, but not explicitly.

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

Conciseness4/5

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

The description is well-structured with a usage line, output summary, and bulleted list of reports. It is concise and front-loaded, though the usage line could be considered redundant.

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 details the output fields (branch count, loop types, etc.) but lacks a formal output schema or return format. It covers input usage and basic output, but misses behavioral transparency and error handling.

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 descriptions for all three parameters. The description adds a usage example and notes zero-based indexing, but does not significantly enhance understanding 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 it analyzes the control flow structure of a method, specifying what it reports (branching, loops, returns, etc.). This distinguishes it from siblings like analyze_data_flow (data flow analysis) and analyze_method (broader analysis).

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?

Provides a usage example and states the prerequisite 'Requires load_project to be called first.' However, it does not explicitly guide when to use this tool versus alternatives 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.

analyze_data_flowA

Analyze data flow within a method.

USAGE: analyze_data_flow(filePath="path/to/File.java", line=10, column=5) OUTPUT: Variables with read/write/declaration info

Reports for each variable:

name and type
whether it is declared, read, written
whether it is a parameter, local variable, or field
return statement count and types

Useful for understanding side effects before extracting methods.

Options:

followCalls: opt-in interprocedural mode (default false). Tracks two fact kinds across argument-to-parameter hops into project callees and reports interproceduralFlows:
- null facts - locals assigned null; sink = a dereference of the tracked value in a callee (potential NPE)
- taint facts - this method's parameters, propagated through aliases and expressions; sink = the value escaping into a non-project (binary) callee May-analysis: reassignments do not kill facts. Returned values are not tracked back into callers.
maxCallDepth: call-edge bound for followCalls (default 2)

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	File containing the method
`line`	Yes	Zero-based line number within the method
`column`	Yes	Zero-based column number
`followCalls`	No	Track null/taint facts across method calls (default false)
`maxCallDepth`	No	Call-edge bound for followCalls (default 2, min 1)

TDQS

A4.1/5.0

Behavior4/5

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

No annotations provided, so the description carries full burden. It explains output details (variables, read/write/declaration info) and provides extensive behavior for followCalls mode, including null and taint facts, may-analysis, and tracking limitations.

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

Conciseness4/5

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

The description is well-structured with sections, starts clearly, and is not overly verbose given the complexity of the tool. It could be slightly more concise but effectively covers key points.

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?

No output schema, but description adequately explains output format. It mentions prerequisite (load_project) and covers all parameters. For the complexity of the tool, it is sufficiently 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?

Schema coverage is 100%, baseline is 3. The description adds value by showing usage format, clarifying zero-based indexing, and explaining followCalls and maxCallDepth in detail beyond schema descriptions.

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 'Analyze data flow within a method' and provides a usage example. It distinguishes itself from sibling tools like analyze_control_flow or analyze_change_impact by focusing on data flow and variable tracking.

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 mentions it is 'useful for understanding side effects before extracting methods' and that it requires load_project first. However, it does not explicitly state when not to use it or compare to alternatives, leaving room for ambiguity.

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

analyze_fileA

Comprehensive file analysis in a single call.

USAGE: analyze_file(filePath="path/to/File.java") OUTPUT: File info, imports, types with member counts, diagnostics

Combines:

File info (path, package, line count)
All imports (with static/on-demand flags)
All types with member counts
Compilation diagnostics (errors/warnings)

Use this instead of multiple calls to get_document_symbols + get_diagnostics.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`includeMembers`	No	Include full member details for each type (default false)
`includeDiagnostics`	No	Include compilation errors/warnings (default true)

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, description bears full transparency burden. It describes tool's combined behavior and default for includeDiagnostics, but does not specify default for includeMembers (false) or any side effects. Minor gap, but overall satisfactory.

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?

Description is highly concise with clear sections (USAGE, OUTPUT, combines list, guideline). Every sentence serves a purpose, no wasted words, effectively front-loaded with key 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?

Given complexity (combines multiple analyses) and no output schema, description provides sufficient overview of what is included. Minor missing detail on includeMembers default, but otherwise complete for selection and invocation.

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, so description adds minimal value beyond illustrating usage (e.g., filePath example). No additional semantics for includeMembers or includeDiagnostics beyond schema, meeting 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?

Description clearly states 'Comprehensive file analysis in a single call' and lists specific components (file info, imports, types with member counts, diagnostics), differentiating it from sibling tools that provide individual analyses.

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 prerequisite 'Requires load_project to be called first' and recommends using this tool instead of multiple calls to get_document_symbols and get_diagnostics, providing clear context for when to use.

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

analyze_methodA

Comprehensive method analysis in a single call.

USAGE: analyze_method(filePath="path/to/File.java", line=N, column=N) OUTPUT: Method info, parameters, exceptions, callers, callees, override info

Combines:

Method info (signature, modifiers, return type)
Parameters with types
Declared exceptions
Incoming calls (who calls this method)
Outgoing calls (what this method calls)
Override information (super method, overriding methods)

Use this instead of multiple calls to get_method_at_position + call hierarchy tools.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number
`maxCallers`	No	Maximum callers to return (default 20)
`maxCallees`	No	Maximum callees to return (default 50)

TDQS

A3.9/5.0

Behavior3/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 that coordinates are zero-based and that the tool combines multiple analyses. However, it does not mention whether the tool is read-only, potential performance impact, authorization requirements, or error handling.

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

Conciseness4/5

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

The description is well-organized with USAGE, OUTPUT, and a bullet-style list of combined information. It is reasonably concise, though the list of outputs could be slightly more compact. Overall, it is front-loaded with the core purpose.

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 absence of an output schema, the description effectively outlines the expected return values. It includes prerequisites (load_project) and a usage example. While it could mention error conditions or limits, it provides sufficient context for an agent to use the tool correctly.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already describes all parameters. The description illustrates usage with filePath, line, and column in an example, and indirectly references maxCallers/maxCallees via the default values in the schema. It adds minimal meaning beyond the schema, achieving the baseline of 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 clearly states the tool performs 'comprehensive method analysis', listing specific outputs (method info, parameters, exceptions, callers, callees, override info). It distinguishes itself from sibling tools like get_method_at_position and call hierarchy tools by stating it combines them.

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 explicitly recommends using this tool instead of multiple calls to get_method_at_position and call hierarchy tools. It also provides a usage example and notes the prerequisite load_project. However, it does not specify when not to use it or list alternatives beyond the combination hint.

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

analyze_typeA

Comprehensive type analysis in a single call.

USAGE: analyze_type(typeName="com.example.Foo") OUTPUT: Type info, members, hierarchy, usage summary, diagnostics

Combines:

Type info (name, kind, modifiers, location)
All members (methods, fields, constructors)
Type hierarchy (superclass, interfaces, subtypes)
Usage summary (instantiations, casts, etc.)
Diagnostics for the type's file

Use this instead of multiple calls to get_type_members + get_type_hierarchy + get_type_usage_summary.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`typeName`	Yes	Fully qualified or simple type name
`includeUsages`	No	Include usage analysis (default true)
`maxUsages`	No	Max usages per category (default 10)

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, description fully covers tool behavior: outputs five categories of analysis. Does not explicitly state read-only nature, but 'analysis' and the listed output categories imply non-destructive behavior.

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

Conciseness5/5

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

Concise with clear structure: brief intro, usage example, output list, combined components, recommendation, and prerequisite. No unnecessary sentences; all information earns its 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?

Given 3 parameters, no output schema, and no annotations, description provides a high-level view of outputs and dependencies. Could improve by detailing output structure or error cases, but current description is adequate.

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%, providing baseline 3. Description adds beyond schema by mentioning default values for includeUsages (true) and maxUsages (10), and includes a usage example for typeName.

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 purpose: 'Comprehensive type analysis in a single call,' listing specific outputs (type info, members, hierarchy, usage summary, diagnostics) and differentiating from sibling tools like get_type_members and get_type_hierarchy.

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 explicit usage example, recommends using this tool instead of multiple separate calls, and states prerequisite ('Requires load_project to be called first'). Does not explicitly list when not to use, but implies it's for combined analysis.

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

apply_cleanupA

Apply a JDT code clean-up to a file and return the rewritten source.

USAGE: apply_cleanup(filePath="path/to/File.java", cleanupId="convert_loops") OUTPUT: changed flag, a label, and the full rewritten source (the file is NOT written — apply the returned source yourself).

Supported cleanupId values: - convert_loops: rewrite index- and iterator-based for loops as enhanced for loops - convert_to_lambda: convert anonymous classes implementing a functional interface to lambdas - pattern_matching_instanceof: use pattern matching for instanceof checks followed by a cast - convert_to_switch_expression: convert assignment/return switch statements to switch expressions - string_concat_to_text_block: convert multi-line string concatenations to text blocks - do_while_rather_than_while: replace while loops that always run once with do-while loops - invert_equals: invert equals() calls so the constant is the receiver (avoids NPEs) - boolean_value_rather_than_comparison: simplify comparisons with boolean literals (x == true -> x) - else_if: collapse else blocks containing a lone if into else-if chains - overridden_assignment: remove initializers that are overwritten before being read

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	Yes	Path to source file
`cleanupId`	Yes	Clean-up to apply (e.g. 'convert_loops')

TDQS

A4.1/5.0

Behavior4/5

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

Explicitly states the output format (changed flag, label, full rewritten source) and clarifies that the file is NOT written. This goes beyond the input schema. No annotations are provided, but the description is transparent about the non-destructive nature and output.

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 highly concise and well-structured: a clear purpose statement, a usage example, output description, and an organized list of supported cleanups. Every sentence adds value without redundancy.

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

Completeness4/5

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

Covers the tool's purpose, parameters, valid values, output, and prerequisite. Missing output schema is compensated by describing the output. Could mention error handling or effect on project state, but overall sufficient for an AI agent.

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

Parameters4/5

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

Schema coverage is 100% with basic descriptions. The description adds significant value by enumerating all valid cleanupId values with explanations for each, enriching the parameter semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it applies JDT code clean-ups to a file and returns rewritten source. It lists all supported cleanup IDs, distinguishing it from siblings like apply_quick_fix and convert_anonymous_to_lambda. However, it does not explicitly compare to siblings.

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 a usage example with parameters and a prerequisite ('Requires load_project to be called first'). Does not state when not to use or specify alternatives, but the example and list offer implicit guidance.

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

apply_quick_fixA

Apply a fix by ID.

USAGE: apply_quick_fix(filePath="...", fixId="add_import:java.util.List") OUTPUT: Text edits to apply the fix

Fix ID formats:

add_import:{fullyQualifiedName} - Add an import statement
remove_import:{index} - Remove import at index
add_throws:{exceptionType} - Add throws declaration to method
surround_try_catch:{exceptionType} - Wrap statement in try-catch

IMPORTANT: Uses ZERO-BASED line numbers.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`fixId`	Yes	The fix ID from get_quick_fixes (e.g., 'add_import:java.util.List')
`line`	No	Zero-based line number (required for some fixes like add_throws)

TDQS

A4.2/5.0

Behavior3/5

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

No annotations, so description carries full burden. Discloses actions (applies fix, outputs text edits) and zero-based line numbers. However, ambiguous whether fix is actually applied or just returns edits. Missing error handling or 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?

Well-structured with summary, usage example, fix format list, and important note. Every sentence adds value, no redundancy.

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

Completeness4/5

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

Covers purpose, parameters, prerequisites, and output. Could clarify whether fix is applied or only computed, but otherwise complete given no output schema.

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 covers all 3 parameters. Description adds value by explaining fix ID patterns and that line is zero-based and required for some fixes, going beyond schema descriptions.

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 'Apply a fix by ID' with a specific verb and resource. It provides fix ID formats and output type, distinguishing it from siblings like get_quick_fixes which only lists fixes.

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?

Includes usage example, fix ID formats, and prerequisite (load_project first). Does not explicitly state when not to use or alternatives, but the context is clear.

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

change_method_signatureA

Change method signature (parameters, return type, or name) and update all call sites.

Returns text edits for the method declaration and all call sites. The caller should apply these edits to perform the change.

USAGE: Position on method declaration, provide changes OUTPUT: Edits for declaration and all call sites

PARAMETER OPERATIONS:

Add new parameter with default value for existing calls
Remove parameter (will remove from calls)
Rename parameter
Reorder parameters (specify all parameters in new order)

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the method
`line`	Yes	Zero-based line number of method declaration
`column`	Yes	Zero-based column number
`newName`	No	New method name (optional, omit to keep current)
`newReturnType`	No	New return type (optional, omit to keep current)
`newParameters`	No	New parameter list. Each item: {name, type, defaultValue?}. Order matters.

TDQS

A4.5/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It transparently discloses that it returns text edits, uses zero-based coordinates, and updates all call sites. Could mention potential conflicts or side effects, but overall adequate.

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

Conciseness5/5

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

Concise with clear sections for usage, output, parameter operations, and important notes. Front-loaded with purpose. Every sentence adds value, no redundancy.

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

Completeness5/5

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

For a complex refactoring tool, the description covers prerequisites, coordinate system, parameter operations, and output format (text edits). No output schema provided, but explanation suffices. Complete and actionable.

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?

Input schema covers all 6 parameters with descriptions (100% coverage). Description adds extra semantics by explaining parameter operations (add, remove, rename, reorder) and default values, which goes beyond 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 verb 'change' and the resource 'method signature', and specifies it updates all call sites. It distinguishes from sibling tools like rename_symbol or extract_method.

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 clear usage context: 'Position on method declaration, provide changes' and prerequisite 'Requires load_project to be called first.' Lacks explicit when-not-to-use or alternatives among siblings, but gives sufficient guidance.

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

convert_anonymous_to_lambdaA

Convert an anonymous class implementing a functional interface to a lambda expression.

Returns the text edit needed to convert the anonymous class to a lambda. The caller should apply this edit to perform the conversion.

USAGE: Position cursor on the 'new' keyword of the anonymous class OUTPUT: Edit to replace anonymous class with lambda

IMPORTANT: Uses ZERO-BASED coordinates. REQUIREMENTS: The anonymous class must implement a functional interface (exactly one abstract method).

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number of anonymous class (on 'new' keyword)
`column`	Yes	Zero-based column number

TDQS

A4.5/5.0

Behavior4/5

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

Describes output as a text edit to be applied, zero-based coordinates, and prerequisite. No annotations exist, so description carries the burden and does so well, though could mention 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?

Structured with clear sections (USAGE, OUTPUT, IMPORTANT, REQUIREMENTS), concise and front-loaded with essential information.

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

Completeness5/5

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

Covers usage, output type, coordinate system, prerequisites, and requirements. No output schema needed as return type is described.

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%, but description adds detail like zero-based coordinates and positioning on 'new' keyword, enhancing meaning beyond 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 converts an anonymous class to a lambda expression, specifying verb, resource, and result. It distinguishes from sibling refactoring 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 explicit usage instructions (cursor on 'new' keyword), requirements (functional interface), and prerequisite (load_project). Lacks explicit when-not-to-use, but context is clear.

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

diagnose_and_fixA

Diagnose a file and compute the quick-fix edits in one call: runs diagnostics, resolves the available fixes per fixable problem, and returns the top fix's edits for each, combined as editsByFile.

USAGE: diagnose_and_fix(filePath="path/to/File.java") OUTPUT: problems (each with its chosen fix when one exists) and editsByFile with the computed edits. NOTHING is written - apply the returned edits yourself.

A file with no fixable diagnostics returns empty problems/edits.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	Yes	Path to source file

TDQS

A4.7/5.0

Behavior5/5

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

The description discloses that no changes are written ('NOTHING is written - apply the returned edits yourself'), and explains the output structure (problems, editsByFile) and behavior for files with no fixable diagnostics. No annotations are provided, so the description fully carries the transparency burden.

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 and well-structured: a purpose sentence, a usage line, an output description, a crucial note about not writing, and a condition for empty results. Every sentence adds value without redundancy.

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

Completeness5/5

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

Given the single parameter, no output schema, and no annotations, the description fully covers the tool's input, output, behavior, and prerequisites. It explains the output format and the condition for empty results, leaving no significant gaps.

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 single parameter 'filePath' has a minimal schema description. The description adds context: it shows the usage format, confirms the file is a source file, and references the prerequisite that load_project must be called. This adds value beyond the schema alone.

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 diagnoses a file and computes quick-fix edits in one call, specifying the verb (diagnose and fix) and resource (file). It distinguishes from siblings like get_diagnostics and apply_quick_fix by combining both steps.

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 a usage example and explicitly states the prerequisite 'load_project' must be called first. It also clarifies that the tool does not write edits. However, it does not explicitly contrast with alternatives like get_quick_fixes+apply_quick_fix, leaving some ambiguity.

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

encapsulate_fieldA

Encapsulate a field: generate a getter/setter pair and rewrite all direct accesses (in this and other files) to go through them.

USAGE: Position on the field name; optionally name the accessors. OUTPUT: editsByFile with all required text edits; warnings from JDT's own condition checking. Edits are returned as text - apply them yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the field
`line`	Yes	Zero-based line number of the field declaration
`column`	Yes	Zero-based column number (on the field name)
`getterName`	No	Getter name (default: getX for field x)
`setterName`	No	Setter name (default: setX for field x)

TDQS

A4.2/5.0

Behavior5/5

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

With no annotations, the description fully explains behavioral details: output format (editsByFile, warnings, text), zero-based coordinates, and that edits are returned and must be applied manually. This is comprehensive and avoids surprises.

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 with 5 sentences, each serving a clear purpose: purpose, usage, output, important note, prerequisite. No waste, front-loaded.

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 no output schema, the description adequately explains the output and prerequisite. It covers what the tool does and how to use it, though it could elaborate slightly on what 'direct accesses' entails. Still fairly complete.

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 adds minimal extra meaning beyond the schema, such as 'optionally name the accessors' correlating to getterName/setterName. No deep parameter semantics added.

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 explicitly states the tool encapsulates a field by generating getter/setter and rewriting direct accesses. It is a specific refactoring verb and resource, distinguishing it from sibling analysis or other refactoring tools.

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 mentions positioning on the field name and optional naming of accessors, but does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives. The prerequisite 'Requires load_project to be called first' is useful context.

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

extract_constantA

Extract an expression into a static final constant at class level.

Returns the text edits needed to extract the expression. The caller should apply these edits to perform the extraction.

USAGE: Select expression by providing start and end positions OUTPUT: Constant declaration and replacement edits

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`startLine`	Yes	Zero-based start line of expression
`startColumn`	Yes	Zero-based start column of expression
`endLine`	Yes	Zero-based end line of expression
`endColumn`	Yes	Zero-based end column of expression
`constantName`	Yes	Name for the constant (should be UPPER_SNAKE_CASE)

TDQS

A4/5.0

Behavior3/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 that the tool returns text edits and that the caller must apply them, implying no direct modification. It also mentions zero-based coordinates. However, it lacks details on error handling, permissions, or side effects, which limits transparency.

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 with a clear structure: purpose, return value, usage, important notes, and prerequisite. Every sentence is necessary and informative, 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?

Given the tool's complexity (6 parameters, no output schema, no annotations), the description covers the essential aspects: what it does, how to use it, and what it returns. It could mention error conditions or coordinate validation, but overall it is fairly complete.

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 baseline is 3. The description adds no new parameter meaning beyond what the schema already provides (e.g., zero-based coordinates, constant name convention). It does not compensate for any missing schema details.

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 purpose: 'Extract an expression into a static final constant at class level.' This distinguishes it from sibling tools like extract_variable (local variable) or extract_method (method), making its purpose specific and unambiguous.

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

Usage Guidelines4/5

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

The description provides explicit usage guidance: 'USAGE: Select expression by providing start and end positions' and notes the prerequisite 'Requires load_project to be called first.' While it doesn't discuss when not to use the tool, it offers sufficient context for correct invocation.

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

extract_interfaceA

Extract an interface from a class containing selected public methods.

Returns the text for a new interface file and edits to add 'implements' clause to the original class.

USAGE: Position on class, provide interface name, optionally specify methods OUTPUT: Interface file content and class modification edit

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the class
`line`	Yes	Zero-based line number of class declaration
`column`	Yes	Zero-based column number
`interfaceName`	Yes	Name for the new interface
`methodNames`	No	Specific method names to include (default: all public non-static methods)

TDQS

A3.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 must cover behavioral traits. It discloses zero-based coordinates and that the output includes interface file content and class modification. However, it does not explicitly state that the tool modifies files (creates new interface and edits class), which is important side-effect information.

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

Conciseness4/5

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

The description is relatively concise and structured with clear sections (USAGE, OUTPUT, IMPORTANT). It is not verbose, though it could be slightly more streamlined.

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 tool has 5 parameters, high schema coverage, and no output schema, the description provides necessary context: prerequisite (load_project), coordinate system, usage pattern, and output type. It is fairly complete for an agent to understand usage.

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 schema already documents all parameters. The description adds minimal extra meaning beyond the schema, such as emphasizing zero-based coordinates. 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 purpose: extract an interface from a class containing selected public methods. It uses specific verbs and resources, and it stands out among sibling tools which are mostly analysis or different refactoring operations.

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 usage instructions: position on class, provide interface name, optionally specify methods. It also notes the prerequisite of calling load_project. However, it does not explicitly exclude use cases or compare to alternatives like extract_method.

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

extract_methodA

Extract a code block into a new method.

USAGE: Select code range, provide method name OUTPUT: Text edits for method declaration and call site

The tool analyzes the selected code to:

Determine which variables become parameters
Determine return type based on variables modified
Generate appropriate method signature

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`startLine`	Yes	Zero-based start line of code to extract
`startColumn`	Yes	Zero-based start column
`endLine`	Yes	Zero-based end line of code to extract
`endColumn`	Yes	Zero-based end column
`methodName`	Yes	Name for the new method

TDQS

A4.2/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 explains that the tool determines parameters and return type, generates method signature and call site, and emphasizes zero-based coordinates. This sufficiently discloses behavioral traits, though it could mention error handling or 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 and well-structured: a one-line summary, clear USAGE and OUTPUT labels, bullet points for analysis details, and a prominent note about zero-based coordinates. Every sentence serves a purpose, and key information is front-loaded.

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 refactoring tool with 6 required parameters and no output schema, the description covers usage, output format, behavioral analysis, coordinate system, and prerequisites. It lacks details on error conditions or return value structure, but overall it is sufficiently complete for correct tool invocation.

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?

Input schema coverage is 100%, so baseline is 3. The description adds context by explaining how parameters (e.g., selection range and method name) are used in the analysis and output generation. This goes beyond the schema's bare descriptions, providing deeper semantic meaning.

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 'Extract a code block into a new method,' which is a specific verb+resource combination. It distinguishes from sibling tools like extract_constant or extract_variable by focusing on method extraction. Additional details about analyzing variables and return types reinforce the 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 provides a usage line ('Select code range, provide method name') and a prerequisite ('Requires load_project to be called first'). However, it does not offer guidance on when to use this tool vs. alternatives like extract_constant or inline_method, nor does it mention conditions to avoid using it.

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

extract_superclassA

Extract a new superclass from a class: the member at the position moves up into a newly created superclass, and the class extends it.

USAGE: Position on the member to extract; provide the new superclass name. OUTPUT: createdFiles carries the new superclass file content; editsByFile carries the source class's edits. Nothing is written - create the file and apply the edits yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the member
`line`	Yes	Zero-based line number of the member declaration
`column`	Yes	Zero-based column number (on the member name)
`superclassName`	Yes	Name for the new superclass

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations provided, the description fully carries the burden of disclosure. It explicitly states that the tool does not write anything ('Nothing is written - create the file and apply the edits yourself'), which is critical for an AI agent to understand the side-effect-free nature of the operation. It also details the output 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 extremely concise with only two short paragraphs. The first sentence immediately states the purpose, followed by a usage summary and important notes. Every sentence adds value without redundancy.

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

Completeness5/5

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

Given the tool's complexity (4 required parameters, no output schema, no annotations), the description covers all necessary contextual information: purpose, usage, coordinate convention, output format, and prerequisite ('Requires load_project'). The agent has enough context to invoke the tool 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 input schema already provides 100% coverage with descriptions for each parameter. The description reinforces the zero-based coordinates but adds no new semantic meaning beyond the schema. Baseline is 3, and the description does not earn a higher score because it restates rather than enriches.

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 ('Extract') and clearly identifies the resource ('new superclass from a class') and the action (moving a member up). It distinguishes from siblings like 'extract_interface', 'extract_method', and 'pull_up' by specifying the creation of a superclass with a member moved up.

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 explicit usage instructions: 'Position on the member to extract; provide the new superclass name.' It also includes important preconditions ('Requires load_project to be called first') and coordinate convention. However, it does not explicitly state when not to use this tool or contrast with similar extraction tools among the many siblings.

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

extract_variableA

Extract an expression at the given position into a local variable.

Returns the text edits needed to extract the expression. The caller should apply these edits to perform the extraction.

USAGE: Select expression by providing start and end positions OUTPUT: Variable declaration and replacement edits

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`startLine`	Yes	Zero-based start line of expression
`startColumn`	Yes	Zero-based start column of expression
`endLine`	Yes	Zero-based end line of expression
`endColumn`	Yes	Zero-based end column of expression
`variableName`	No	Name for the new variable (optional, will suggest if not provided)

TDQS

A4.5/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 disclosure. It states that the tool returns text edits (not applying them) and uses zero-based coordinates, and requires load_project. It adequately communicates the non-destructive, edit-returning behavior.

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

Conciseness5/5

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

The description is concise: four sentences covering purpose, output, usage, and prerequisite. Every sentence adds value without redundancy, and the structure is front-loaded with the core action.

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

Completeness5/5

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

Given the tool's complexity as a refactoring operation and the lack of an output schema, the description adequately explains what it does (extracts to variable), what it returns (text edits), the coordinate system (zero-based), and the prerequisite (load_project). No critical gaps are present.

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 has 100% description coverage. The description reinforces the use of zero-based coordinates and aligns with parameters (start and end positions). It adds meaning beyond the schema by highlighting the zero-based requirement and the optional variableName parameter.

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 explicitly states the tool's purpose: 'Extract an expression at the given position into a local variable.' It specifies the verb 'Extract' and the resource 'expression into a local variable,' clearly distinguishing it from sibling tools like extract_constant and extract_method.

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 usage guidelines: 'Select expression by providing start and end positions' and 'Requires load_project to be called first.' It implies when to use (extracting to a local variable) but does not explicitly exclude alternatives or mention when not to use.

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

find_affected_testsA

Find the test methods that exercise a symbol, directly or transitively.

USAGE: find_affected_tests(filePath="path/to/File.java", line=10, column=5) OUTPUT: Test methods (JUnit 4/5, TestNG) from which the symbol is reachable, with locations - the set of tests to run after changing it.

The caller walk follows calls, instantiations, field accesses, and override declarations (a test calling through an interface or superclass covers the implementation). Non-test intermediate methods are walked through but not reported. Disabled tests are included with disabled=true (they cover the code but will not run). A symbol no test reaches returns an empty set.

Supports project methods, fields, and types as the target symbol.

Options:

maxResults: cap the reported list (default 100)

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	File containing the symbol
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number
`maxResults`	No	Maximum test methods to return (default 100)

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description fully covers behavioral traits: the caller walk mechanism, inclusion of disabled tests, handling of unreachable symbols, and support for methods, fields, types. It transparently describes what happens in various scenarios.

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

Conciseness5/5

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

The description is well-structured with clear sections: purpose, usage, output, details, options, prerequisite. It is concise yet comprehensive, using bullet points and plain language effectively.

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

Completeness5/5

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

Given no output schema, the description thoroughly explains the output format, including disabled tests and empty sets. It covers all necessary aspects of the tool's operation, making it complete and useful.

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%, giving baseline 3. The description adds value by providing a usage example, explaining the coordinate parameters, and clarifying the maxResults option. This enhances understanding 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's purpose: 'Find the test methods that exercise a symbol, directly or transitively.' It provides a usage example and distinguishes itself from siblings like 'find_tests' by focusing on affected tests, not all tests.

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 includes a prerequisite ('Requires load_project to be called first') and explains the context ('the set of tests to run after changing it'). It does not explicitly state when not to use it, but it provides clear guidance for intended use.

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

find_annotation_usagesA

Find all usages of an annotation type in the project.

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified annotation name as typeName OUTPUT: All locations where the annotation is applied

Examples:

find_annotation_usages(typeName="org.springframework.beans.factory.annotation.Autowired")
find_annotation_usages(typeName="org.junit.jupiter.api.Test")
find_annotation_usages(typeName="javax.persistence.Entity")

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Fully qualified annotation type name (e.g., 'org.springframework.beans.factory.annotation.Autowired')
`maxResults`	No	Maximum results to return (default 100)

TDQS

A4.2/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 full behavioral burden. It states output as 'All locations where the annotation is applied' and mentions the prerequisite. However, it does not specify the output format (e.g., file paths, line numbers) or error behavior (e.g., if annotation is not found). This leaves some ambiguity for the agent.

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: three sentences plus a bulleted example list. It is front-loaded with purpose, then provides uniqueness, usage, output, examples, and prerequisite in a logical order. No superfluous words. Every sentence adds necessary 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers key aspects: purpose, input format, output summary, prerequisite, and examples. It lacks details on default pagination (maxResults default 100) and error handling, but these are minor given the examples and schema. Overall, it is mostly complete for effective use.

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 description adds value by providing examples of fully qualified annotation names, which clarifies the required format. It also reinforces the parameter usage. Although the schema already describes typeName sufficiently, the examples make it more actionable.

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 purpose: 'Find all usages of an annotation type in the project.' It uses a specific verb+resource (find usages of annotation type) and distinguishes itself from siblings via the 'JDT-UNIQUE' note and by providing examples that show its specialization for annotations. This differentiates it from generic search tools like find_references or find_implementations.

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 usage guidelines: 'Provide fully qualified annotation name as typeName' and 'Requires load_project to be called first.' It implies the tool is for Java projects (JDT) and is unique compared to LSP. However, it does not explicitly tell when to use this tool over alternatives like find_references or find_implementations, which would further improve clarity.

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

find_castsA

Find all casts to a type ((Foo) x expressions).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified type name OUTPUT: All locations where casting to this type occurs

Useful for:

Identifying unsafe downcasts
Finding refactoring opportunities (replace cast with polymorphism)
Understanding type conversion patterns

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Fully qualified type name to find casts to
`maxResults`	No	Maximum results to return (default 100)

TDQS

A4.1/5.0

Behavior3/5

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

No annotations provided, so description must cover behavior. It states output is locations of casts, but does not mention format, performance, or error handling. Adequate for basic understanding.

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

Conciseness4/5

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

Concise and well-structured with labeled sections (JDT-UNIQUE, USAGE, OUTPUT, etc.). Front-loaded with purpose. No unnecessary sentences.

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 two parameters, no output schema, and many sibling tools, the description sufficiently covers what the tool does and returns. Could mention output format, but not necessary.

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% (both parameters described). Description adds value by specifying typeName must be fully qualified and maxResults default is 100, beyond 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?

Clearly states it finds all casts to a given type using JDT-specific fine-grained search. Differentiates from sibling tools (e.g., find_references) by being specific to casting expressions.

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 clear usage: provide fully qualified type name, requires load_project first. Lists explicit use cases (unsafe downcasts, refactoring). Does not discuss when not to use, but context is sufficient.

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

find_catch_blocksA

Find all catch blocks for an exception type (catch(ExceptionType e)).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified exception type name as typeName OUTPUT: All catch blocks that handle this exception type

Useful for:

Understanding exception handling patterns
Finding all handlers for a specific exception
Exception handling analysis and refactoring

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Fully qualified exception type name (e.g., 'java.io.IOException')
`maxResults`	No	Maximum results to return (default 100)

TDQS

A4.1/5.0

Behavior3/5

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

With no annotations provided, the description is responsible for behavioral disclosure. It explains that the tool searches for catch blocks and returns them, but does not explicitly state that it is a read-only operation or disclose any side effects. The behavioral traits are implied but not fully 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?

The description is concise and well-structured: it starts with the core purpose, then uniqueness, usage, output, use cases, and prerequisite. Every sentence adds value without unnecessary verbosity.

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 absence of an output schema, the description adequately specifies the output ('All catch blocks that handle this exception type'). It covers input, usage context, prerequisites, and use cases, making it complete for this tool's complexity.

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 covers 100% of parameters with descriptions. The description adds limited value beyond reinforcing the schema ('Provide fully qualified exception type name'). No additional meaning or nuances are provided, so a 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 clearly states the tool's purpose: 'Find all catch blocks for an exception type'. It uses a specific verb and resource, and distinguishes itself from sibling tools like find_references or find_throws_declarations by focusing exclusively on catch blocks.

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 indicates when to use the tool (e.g., understanding exception handling, finding handlers) and mentions prerequisite ('Requires load_project to be called first'). It also notes uniqueness ('JDT-UNIQUE'). It could be improved by explicitly stating when not to use it, but the guidance is clear.

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

find_circular_dependenciesA

Detect cycles in packages.

USAGE: find_circular_dependencies() USAGE: find_circular_dependencies(packageFilter="com.example") OUTPUT: List of circular dependency cycles

Uses Tarjan's SCC algorithm to efficiently detect all cycles. Reports cycle paths and affected packages.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`packageFilter`	No	Package prefix to analyze (default: all project packages)
`maxCycleLength`	No	Maximum cycle length to report (default: 10)

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided. The description mentions the algorithm (Tarjan's SCC) and output (cycle paths and affected packages), which offers some behavioral insight. However, it does not discuss performance, side effects, or behavior when no cycles exist.

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

Conciseness4/5

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

The description is relatively concise, but the two usage lines are somewhat redundant. It is well-structured with clear sections for usage and output, though minor trimming could improve efficiency.

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 covers purpose, usage, and a prerequisite. However, with no output schema, the return format is only vaguely described as 'List of circular dependency cycles'. More detail on the output structure would improve completeness.

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?

Input schema has 100% coverage with descriptions. The description adds value by showing usage examples for 'packageFilter', but does not mention 'maxCycleLength'. Overall, it neither significantly enhances nor harms understanding 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 'Detect cycles in packages' and provides usage examples. The tool name is self-explanatory, and the description distinguishes it from generic analysis tools like analyze_control_flow.

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 includes the prerequisite 'Requires load_project to be called first' and shows usage patterns. It does not explicitly contrast with siblings, but the tool's specificity makes its use case clear.

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

find_field_writesA

Find all write accesses (mutations) to a field.

USAGE: Position cursor on a field declaration or reference OUTPUT: List of locations where the field is modified

IMPORTANT: Uses ZERO-BASED coordinates.

Unlike find_references which returns all usages, this returns only locations where the field value is changed (assignments, increments, etc). Useful for data flow analysis and understanding state mutations.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number
`maxResults`	No	Max write locations to return (default 100)

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description explains important behaviors: zero-based coordinates, output is a list of modification locations, and the prerequisite. Could mention if it searches across files or just current project, but covers key 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?

Concise 7-line description; front-loaded with purpose, then usage, output, coordinate system, sibling distinction, and prerequisite. No redundant sentences.

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 tool with no output schema, it describes the output (list of locations) and prerequisites. Could be more explicit about scope (e.g., entire project) and performance, but overall complete enough for the task.

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 description adds no new parameter meaning beyond the schema. The mention of zero-based coordinates is also in the schema. Baseline 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?

Clearly states 'Find all write accesses (mutations) to a field' with specific verb and resource, and explicitly distinguishes itself from the sibling tool 'find_references' by noting it returns only modification locations.

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 usage context ('Position cursor on a field declaration or reference'), mentions prerequisite ('Requires load_project to be called first'), and contrasts with 'find_references'. Lacks explicit when-not-to-use but the sibling contrast gives good guidance.

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

find_implementationsA

Find implementations of an interface or extensions of a class.

USAGE: Position on a type (interface or class), find all implementors/subclasses OUTPUT: List of implementing/extending types with locations

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number
`maxResults`	No	Max implementations to return (default 100)

TDQS

A4.4/5.0

Behavior4/5

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

No annotations provided; description adequately discloses zero-based coordinates and requirement for prior project loading. Could add more about error handling or behavior when not on a type, but sufficient.

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

Conciseness5/5

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

Very concise with clear labeled sections (USAGE, OUTPUT, IMPORTANT). No unnecessary words; every sentence provides essential 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?

Covers key aspects: what it does, prerequisites, output type, and coordinate system. No output schema, but output described. Could mention empty result case, but not critical for functionality.

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%, baseline 3. Description adds value by emphasizing zero-based coordinates for line and column, and mentioning default for maxResults (100).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it finds implementations of interfaces or extensions of classes. Distinguishes from siblings like find_references and get_type_hierarchy by specifying the scope (implementors/subclasses) and usage position on type.

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

Usage Guidelines4/5

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

Explicitly states prerequisite (load_project) and usage context (position on a type). Does not mention when to avoid this tool versus alternatives, but the purpose is specific enough.

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

find_instanceof_checksA

Find all instanceof checks for a type (x instanceof Foo).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified type name OUTPUT: All locations where instanceof checks against this type occur

Useful for:

Identifying type checking patterns
Finding polymorphism opportunities (replace instanceof with virtual dispatch)
Understanding type discrimination logic

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Fully qualified type name to find instanceof checks for
`maxResults`	No	Maximum results to return (default 100)

TDQS

A4.3/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It discloses the operation (find), output (locations), and prerequisite. Could mention read-only nature, but overall adequate.

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?

Very concise: three sentences plus bullet points. Front-loaded with main purpose. No redundant information.

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

Completeness5/5

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

Given no output schema and no annotations, description covers essential aspects: purpose, usage, prerequisite, output, and use cases. Complete for a search 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 coverage is 100%, baseline 3. Description adds minimal extra meaning: specifies fully qualified type name for typeName, but no extra details on maxResults beyond 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?

Clearly states 'Find all instanceof checks for a type (x instanceof Foo)' using a specific verb and resource. The JDT-UNIQUE note distinguishes it from sibling 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 clear usage context: 'Provide fully qualified type name' and prerequisite 'Requires load_project to be called first.' Lists use cases but lacks explicit when-not-to-use or alternatives.

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

find_large_classesA

Find classes that exceed size thresholds.

USAGE: find_large_classes(maxMethods=20, maxFields=10, maxLines=300) OUTPUT: List of classes exceeding any threshold with their metrics

Default thresholds:

maxMethods: 20 methods
maxFields: 10 fields
maxLines: 300 lines

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`maxMethods`	No	Maximum methods before flagging (default 20)
`maxFields`	No	Maximum fields before flagging (default 10)
`maxLines`	No	Maximum lines before flagging (default 300)

TDQS

A3.9/5.0

Behavior3/5

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

No annotations provided, so description carries the burden. It mentions output is a list of classes with metrics but doesn't disclose if it's read-only or any side effects. Basic information is present but additional behavioral details are missing.

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

Conciseness4/5

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

Concise and well-structured, with the main purpose upfront. The usage example and default thresholds are helpful without being verbose.

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 no output schema, the description adequately describes output format and prerequisites. Could mention error handling, but overall complete for a straightforward query 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 coverage is 100%, and description reiterates defaults and meanings, adding little beyond the schema. Baseline 3 applies as description does not significantly enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds classes exceeding size thresholds, with specific metrics (methods, fields, lines). Among siblings like find_unused_code, this tool stands out for its focus on size metrics.

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 a usage example with default thresholds and explicitly states 'Requires load_project to be called first.' However, it does not specify when to use this tool over other analysis tools.

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

find_method_referencesA

Find all method reference expressions (Foo::bar lambda syntax).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Position on a method, or provide method details OUTPUT: All locations where the method is used as a method reference

Useful for:

Understanding functional programming patterns
Finding lambda-style usages of methods
Refactoring analysis

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the method
`line`	Yes	Zero-based line number of the method
`column`	Yes	Zero-based column number
`maxResults`	No	Maximum results to return (default 100)

TDQS

A3.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 full burden. It discloses use of zero-based coordinates and the load_project prerequisite, but does not detail output format, error handling, or constraints like the default maxResults limit. The output is described as 'all locations' without specifics, which may be slightly misleading given the maxResults parameter.

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

Conciseness4/5

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

The description is well-structured with sections for usage, output, and important notes. It is concise but includes some generic 'Useful for' bullet points that may not add significant value for an AI agent. Overall, it earns its space with clear organization.

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 no output schema, the description should explain what 'locations' contain. It fails to specify the format of output (e.g., file paths, line numbers). It does mention prerequisites and zero-based coordinates, which are helpful, but missing details on error cases and default limits reduce completeness.

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 description adds limited value. It reinforces zero-based coordinates already described in the schema but does not elaborate on filePath or maxResults beyond what the schema provides. The description's mention of 'maxResults' is absent, leaving the schema to bear full parameter meaning.

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 method reference expressions (Foo::bar lambda syntax), distinguishing it from the sibling 'find_references' which likely finds all references. It specifies JDT-UNIQUE and not available in LSP, providing precise purpose.

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 usage instruction: 'Position on a method, or provide method details' and emphasizes zero-based coordinates. It also specifies a prerequisite: 'Requires load_project to be called first.' However, it does not explicitly state when not to use this tool or compare with alternatives like 'find_references'.

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

find_naming_violationsA

Check code against standard Java naming conventions.

USAGE: find_naming_violations(filePath="path/to/File.java") OUTPUT: List of naming convention violations

Conventions checked:

Classes/interfaces/enums: PascalCase
Methods: camelCase
Fields: camelCase
Constants (static final): UPPER_SNAKE_CASE
Parameters: camelCase

If filePath is omitted, scans all project files.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	No	File to check (omit to scan all files)

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description fully discloses the tool's behavior: it checks naming conventions and lists violations. It enumerates the specific conventions checked. There's no mention of destructive actions, as it is a read-only analysis.

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

Conciseness5/5

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

The description is well-structured with a brief summary, usage pattern, output expectation, list of conventions, and additional notes. Every sentence adds value, and it is concise without being terse.

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

Completeness5/5

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

Given the tool has no output schema, the description adequately explains output as a list of violations. It covers the conventions checked, parameter behavior, and prerequisites, making it complete for an AI agent to understand and use the tool correctly.

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

Parameters4/5

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

Schema coverage is 100% with one parameter. The description adds value beyond the schema by providing a usage example and clarifying that omitting filePath scans all project files, which is not immediately clear from the schema description alone.

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 explicitly states 'Check code against standard Java naming conventions,' with a clear verb and resource. It distinguishes itself from siblings by focusing specifically on naming violations, a unique task among the listed 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?

The description provides a usage example, explains the optional filePath parameter, and mentions the prerequisite 'Requires load_project to be called first.' It lacks explicit when-not-to-use or alternatives, but the 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.

find_possible_bugsA

Find possible bugs and code quality issues.

USAGE: find_possible_bugs() USAGE: find_possible_bugs(filePath="path/to/File.java") OUTPUT: List of potential issues

Detects:

Null pointer risks (dereferencing potentially null values)
Resource leaks (unclosed streams, connections)
Empty catch blocks
Comparison issues (== on objects instead of equals)
Synchronization issues (sync on String)

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	No	Optional: specific file to check (default: all files)
`severity`	No	Filter by severity: high, medium, low, all (default: all)

TDQS

A3.7/5.0

Behavior3/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 types of issues detected and the prerequisite, but does not mention side effects, permissions, or performance implications. It implies a read-only operation but doesn't state it explicitly.

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

Conciseness4/5

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

The description is well-organized with usage examples, output hint, and a bulleted list. It is concise (no filler) and front-loads the purpose. Minor redundancy (repeating 'USAGE') is acceptable for clarity.

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 static analysis tool with no output schema, the description gives a good overview of capabilities and a key prerequisite. It could detail the output format more, but the list of detected issues provides sufficient context 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?

The input schema has 100% coverage for both parameters (filePath, severity). The description adds the usage example for filePath and clarifies it's optional, but does not elaborate on severity or any format constraints. The schema already does most of the work.

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 bugs and code quality issues, listing specific detection types (null pointer risks, resource leaks, etc.). This distinguishes it from sibling tools like 'find_naming_violations' or 'analyze_control_flow' which target different aspects.

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?

It provides usage examples and a prerequisite ('Requires load_project to be called first'). However, it does not explicitly guide when to use this tool over alternatives (e.g., 'analyze_file') or when not to use it. The guidance is minimal but functional.

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

find_referencesA

Find all references to a symbol across the project.

USAGE: Position on symbol, find all usages OUTPUT: List of reference locations with context

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number
`maxResults`	No	Max references to return (default 100)

TDQS

A4.1/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 discloses important behavioral traits: zero-based coordinates and the prerequisite to call load_project. However, it does not mention potential side effects or whether results are limited to maxResults, which is inferred from the parameter.

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

Conciseness4/5

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

The description is concise with sections (USAGE, OUTPUT, IMPORTANT) and avoids repetition. It is front-loaded with the purpose and key details, though the formatting could be more 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?

Given the complexity of a symbol reference tool and no output schema, the description adequately covers prerequisites, coordinate system, and basic usage. It is reasonably complete for an agent to invoke 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 covers 100% of parameters, but the description adds value by emphasizing the 'ZERO-BASED coordinates' for line and column, and implying a default of 100 for maxResults. This clarifies the parameter semantics 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 'Find all references to a symbol across the project' with a specific verb (find) and resource (references). Among sibling tools like find_implementations and find_method_references, this tool is distinguished as the generic reference finder.

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 includes a prerequisite ('Requires load_project to be called first') and a usage hint ('Position on symbol, find all usages'), but does not explicitly differentiate when to use this tool versus siblings like find_method_references or find_implementations.

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

find_reflection_usageA

Find places where Java reflection API is used.

USAGE: find_reflection_usage() OUTPUT: All reflection calls grouped by method type

Detects calls to:

Class.forName(), Class.newInstance()
Class.getMethod/getDeclaredMethod/getField/getDeclaredField
Class.getConstructor/getDeclaredConstructor
Method.invoke(), Field.get/set(), Constructor.newInstance()

These usages are invisible to static reference searches and can break when types or methods are renamed.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`maxResults`	No	Maximum results per reflection method (default 100)

TDQS

A4.1/5.0

Behavior4/5

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

No annotations provided, so description bears full burden. It explains the tool detects specific reflection methods, groups by method type, and that these usages are invisible to static searches and can break on renames. Implicitly read-only, but no explicit statement of non-destructive nature.

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

Conciseness4/5

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

Description is structured with usage, output, and list. Front-loaded with purpose. Minor inconsistency: usage line shows no parameters, but parameter exists, but overall concise and informative.

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?

Covers prerequisite, output format (grouped by method type), and rationale. Missing error handling for missing load_project, but output schema not required. Adequate for a single-parameter 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 covers parameter 'maxResults' with description. Description does not add additional meaning beyond what schema provides. Baseline 3 because schema coverage is 100%.

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 a specific verb (find) and resource (Java reflection API usage). It lists exact methods detected, making it highly specific and distinguishable from siblings like 'find_references'.

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?

Description clearly states prerequisite ('Requires load_project to be called first') and why to use it (reflection calls invisible to static reference searches). Does not explicitly mention when not to use, but context is clear.

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

find_testsA

Find test classes and methods in the project.

USAGE: find_tests() OUTPUT: List of test classes with their test methods

Supports:

JUnit 4 (@Test, @Before, @After, etc.)
JUnit 5 (@Test, @BeforeEach, @AfterEach, etc.)
TestNG annotations

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`pattern`	No	Filter test classes by name pattern (glob)
`includeDisabled`	No	Include disabled/ignored tests (default false)

TDQS

A3.9/5.0

Behavior3/5

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

No annotations provided. Description implies read-only operation via 'Find' and describes output format. Does not explicitly state absence of 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.

Conciseness5/5

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

Very concise, front-loads purpose, uses bullet-like structure. Every line adds value, 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?

Covers main purpose, prerequisites, supported frameworks, and output. Lacks details on return format, error handling, or behavior when pattern matches nothing.

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%; parameters are documented in schema. Tool description adds no extra parameter semantics beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it finds test classes and methods, lists supported frameworks (JUnit 4, 5, TestNG). Distinct from sibling tools which focus on different analysis tasks.

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 a usage example and explicitly states prerequisite (require load_project). No comparison to alternatives, but context is clear enough for typical use.

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

find_throws_declarationsA

Find all throws declarations of an exception type in method signatures.

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified exception type name as typeName OUTPUT: All methods that declare 'throws ExceptionType'

Useful for:

Understanding exception flow in the codebase
Finding all methods that can throw a specific exception
Exception handling analysis

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Fully qualified exception type name (e.g., 'java.io.IOException')
`maxResults`	No	Maximum results to return (default 100)

TDQS

A4.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 full burden. It discloses the search scope (throws declarations in method signatures only), input format, and prerequisite. It also notes the JDT-UNIQUE nature. Could be more comprehensive (e.g., case sensitivity, subclass handling), but overall informative.

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

Conciseness5/5

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

The description is well-structured: purpose, uniqueness note, usage format, output, use cases, prerequisite. Every sentence adds value with no repetition or fluff. Size is appropriate for the tool's simplicity.

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 tool has 2 parameters, no output schema, and no annotations, the description covers purpose, usage, use cases, and prerequisite. It is sufficient for an agent to understand when and how to use it. Minor omission: output format details (e.g., whether fully qualified method names are returned). Still, it is reasonably complete.

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 descriptions for both parameters. The description reinforces the schema for typeName but adds no new meaning. For maxResults, no additional semantics are provided. Baseline 3 is appropriate when schema already documents parameters adequately.

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 'Find' and resource 'throws declarations of an exception type in method signatures.' It specifies input (fully qualified exception type) and output (list of methods). The JDT-UNIQUE note distinguishes it from LSP-based siblings, and no sibling tool duplicates this focused search.

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?

Description provides explicit usage instructions ('Provide fully qualified exception type name'), lists use cases, and mentions a prerequisite ('Requires load_project to be called first'). However, it does not explicitly state when to avoid this tool in favor of alternatives, though the JDT-UNIQUE note implies its unique value.

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

find_type_argumentsA

Find all usages of a type as a generic type argument (List, Map<K, Foo>).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified type name OUTPUT: All locations where the type is used as a generic argument

Useful for:

Understanding generic usage patterns
Finding all collections/containers of a type
API design analysis

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Fully qualified type name to find in generic arguments
`maxResults`	No	Maximum results to return (default 100)

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description must disclose behavioral traits. It mentions the JDT-specific nature and prerequisite but does not explicitly state the tool is read-only or explain any side effects or performance implications. The description provides some context but not full transparency.

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

Conciseness4/5

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

The description is well-structured with sections (JDT-UNIQUE, USAGE, OUTPUT, Useful for, Requires) and front-loaded with the main purpose. It is reasonably concise, though the 'Useful for' list adds minor redundancy.

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 no output schema, the description only says 'All locations where the type is used as a generic argument', lacking detail on output format (e.g., file paths, line numbers). For a search tool, more specifics about the result structure would be beneficial, but it provides the essential functionality 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 descriptions for both parameters (typeName, maxResults). The description reiterates the need for a fully qualified type name but adds no additional semantics beyond the schema. The baseline of 3 is appropriate as description does not enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds all usages of a type as a generic type argument, with examples like List<Foo>. It distinguishes itself as JDT-UNIQUE, unavailable in LSP, making the 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 specifies the prerequisite 'Requires load_project to be called first' and suggests useful scenarios like understanding generic patterns. However, it does not explicitly compare to sibling tools like find_references or find_type_instantiations, missing clear when-to-use vs alternatives guidance.

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

find_type_instantiationsA

Find all instantiations of a type (new Foo() calls).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified type name OUTPUT: All locations where the type is instantiated with 'new'

Useful for:

Understanding object creation patterns
Identifying factory method candidates
Finding coupling points

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Fully qualified type name (e.g., 'java.util.ArrayList')
`maxResults`	No	Maximum results to return (default 100)

TDQS

A3.9/5.0

Behavior3/5

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

No annotations provided, so description carries full burden. It describes output as locations with 'new' calls, but does not explicitly state read-only nature or other behavioral traits. It mentions load_project prerequisite, but could disclose more 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.

Conciseness4/5

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

Concise with clear sections: purpose, JDT-UNIQUE, usage, output, useful for, prerequisite. Slight redundancy in stating output after purpose, but overall efficient.

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

Completeness4/5

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

For a simple search tool with 2 parameters, no output schema, and no annotations, the description is sufficient. Covers purpose, usage, output, and prerequisite. Could mention error handling, but not necessary.

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 good descriptions. Description restates 'fully qualified type name' and hints at maxResults default, adding little beyond schema. Baseline 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 finds instantiations of a type (new Foo() calls), with a specific verb and resource. It distinguishes from siblings by noting JDT-UNIQUE fine-grained search not in LSP.

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 clear usage: provide fully qualified type name, and prerequisite (load_project). Mentions use cases. Does not explicitly state when not to use or list alternatives, but the JDT-UNIQUE note implies uniqueness.

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

find_unreachable_codeA

Find code unreachable from any entry point, project-wide.

USAGE: find_unreachable_code() OUTPUT: Members (types, methods, fields) that no entry point reaches, with visibility and location, plus the roots used.

Roots are public static void main(String[]) methods and detected test methods (JUnit 4/5, TestNG; disabled tests still count). Reachability follows calls, instantiations, field accesses, field initializers, and overrides (a call through an interface or superclass reaches every override). A type is reported only when neither it nor any of its members is reachable.

IMPORTANT: results mean "unreachable from declared entry points", not "safe to delete" - reflection, dependency injection, and serialization entry points are invisible to the graph.

Options:

includeTestRoots: count test methods as entry points (default true)
maxResults: cap the reported list (default 100)

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`includeTestRoots`	No	Treat test methods as entry points (default true)
`maxResults`	No	Maximum entries to return (default 100)

TDQS

A4.9/5.0

Behavior5/5

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

No annotations are provided, so the description fully discloses behavior: how reachability is computed (calls, instantiations, field accesses, etc.), what counts as roots (main methods, test methods), and what the output includes (members with visibility and location). It also clarifies that disabled tests still count as entry points.

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

Conciseness5/5

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

The description is well-structured with clear sections (USAGE, OUTPUT, explanation of roots, IMPORTANT caveats, Options). It is concise yet comprehensive, with every sentence adding necessary information.

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

Completeness5/5

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

Given the tool's complexity, the description is complete: it explains the algorithm, the meaning of results, limitations (invisible entry points), and prerequisites. No output schema is provided, but the description sufficiently covers the output format.

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 description coverage is 100%, so baseline is 3. The description adds value by explaining defaults ('default true' for includeTestRoots, 'default 100' for maxResults) and context for the options, which goes beyond the schema's type descriptions.

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 purpose: 'Find code unreachable from any entry point, project-wide.' It distinguishes this from sibling tools like 'find_unused_code' by specifying the project-wide scope and entry point focus.

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 syntax, outlines options, and gives a critical caveat: results indicate unreachability from declared entry points, not safe-to-delete due to reflection and DI. It also notes the prerequisite 'Requires load_project to be called first.'

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

find_unused_codeA

Find unused private methods and fields in the project.

USAGE: find_unused_code() USAGE: find_unused_code(filePath="path/to/File.java") OUTPUT: List of unused private members

Detects:

Unused private methods
Unused private fields
Write-only fields (set but never read)

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	No	Optional: specific file to check (default: all files)
`includeFields`	No	Include unused fields (default true)
`includeMethods`	No	Include unused methods (default true)

TDQS

A4.2/5.0

Behavior3/5

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

No annotations provided, so description must carry full burden. It describes what it detects and the prerequisite, but does not explicitly state it is read-only (implied by 'find') or mention side effects, performance, 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.

Conciseness5/5

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

Concise and well-structured: title, usage examples, output description, detection list, prerequisite. Every sentence is informative with no redundancy.

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

Completeness4/5

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

Covers purpose, usage, output format, detection categories, and prerequisite. Lacks error handling details and output schema (since none provided). Adequate for the tool's complexity.

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 description adds value by showing usage examples with the optional filePath parameter and default behavior (includeFields/methods default true).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it finds unused private methods and fields, listing specific detection categories (unused private methods, unused private fields, write-only fields). This distinguishes it from sibling tools like find_references or find_method_references.

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 two usage examples and explicitly states that load_project must be called first. However, it does not differentiate from sibling tools or give when-not-to-use guidance.

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

get_call_hierarchy_incomingA

Find all callers of a method (incoming calls).

USAGE: Position cursor on a method name OUTPUT: List of methods that call this method

IMPORTANT: Uses ZERO-BASED coordinates.

Useful for understanding who depends on a method before changing it.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number
`maxResults`	No	Max callers to return (default 50)

TDQS

A3.8/5.0

Behavior3/5

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

No annotations provided, so description carries full burden. Discloses zero-based coordinates and prerequisite load_project. However, it does not mention side effects, error behavior, or output format beyond 'list of methods'. Adequate but not richly transparent.

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

Conciseness4/5

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

Description is concise with 6 lines, front-loaded with purpose. Each sentence adds value (usage, output, coordinate note, prerequisite). Minimal fluff, but could be slightly more structured.

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 no output schema, description minimally states 'OUTPUT: List of methods that call this method' but lacks details on result structure (e.g., what fields each method entry has). Also misses any ordering or deduplication info. Adequate but incomplete.

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 baseline is 3. Description does not add additional meaning beyond the schema; it only reiterates zero-based coordinates already in schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Find all callers of a method (incoming calls)' with a specific verb and resource. It distinguishes from sibling tool get_call_hierarchy_outgoing by using 'incoming' in both name and description.

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 explicit usage context: 'USAGE: Position cursor on a method name' and prerequisite 'Requires load_project to be called first.' Does not explicitly mention when not to use or alternatives, but the naming and description differentiate from the outgoing sibling.

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

get_call_hierarchy_outgoingA

Find all methods called by a method (outgoing calls).

USAGE: Position cursor on a method name OUTPUT: List of methods that this method calls

IMPORTANT: Uses ZERO-BASED coordinates.

Useful for understanding what a method depends on.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A4.3/5.0

Behavior4/5

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

Discloses important behavioral details: zero-based coordinates and prerequisite dependency. No annotations are present, so the description carries full burden; it adequately describes usage constraints but could mention read-only nature or 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.

Conciseness4/5

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

Concise with six sentences; uses clear labels (USAGE, OUTPUT, IMPORTANT). Every sentence adds value, though minor redundancy could be trimmed.

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 no output schema and no annotations, the description covers purpose, usage, coordinates, and prerequisite. Lacks detail on error cases or output format, but sufficient for typical use.

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% with descriptions for all three parameters. The description adds value by clarifying the coordinate system is zero-based, which is significant beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool finds methods called by a method (outgoing calls), distinguishing it from incoming call hierarchy. The verb 'Find' and resource 'methods called by a method' are specific and unambiguous.

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

Usage Guidelines4/5

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

Provides explicit usage instructions ('Position cursor on a method name') and a prerequisite ('Requires load_project to be called first'). Does not explicitly exclude alternative tools or compare to siblings, but the 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.

get_classpath_infoA

Get project classpath information.

USAGE: Call to get all classpath entries for the loaded project OUTPUT: Source folders, libraries, and classpath containers

Useful for understanding project structure and dependencies.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`includeLibraries`	No	Include library entries (default true)
`includeSource`	No	Include source folder entries (default true)
`includeContainers`	No	Include container entries like JRE (default true)

TDQS

A3.9/5.0

Behavior3/5

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

No annotations exist, so the description carries full burden. It describes output and a prerequisite but does not disclose side effects, errors, or performance implications. Adequate 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?

Description is concise with a clear structure: purpose, usage, output, and prerequisite. No redundant sentences.

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 no output schema, the description explains the return content (source folders, libraries, containers) and a prerequisite. Could specify return format more precisely, but it is complete enough for most use cases.

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% with clear parameter descriptions. The tool description adds value by mapping parameters to output categories (libraries, source, containers), enhancing understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves classpath information and lists output categories (source folders, libraries, containers). It is specific but does not explicitly differentiate from sibling tools like get_project_structure or get_dependency_graph.

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 a usage statement and a clear prerequisite ('Requires load_project to be called first'). However, no guidance is given on when to use this tool versus alternatives 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.

get_complexity_metricsA

Get cyclomatic complexity, cognitive complexity, LOC.

USAGE: get_complexity_metrics(filePath="path/to/File.java") OUTPUT: Complexity metrics with risk assessment

Metrics:

Cyclomatic Complexity: Count of decision points (+1 for if/for/while/case/catch)
Cognitive Complexity: Penalizes nesting and breaks in linear flow
LOC: Physical and logical lines of code

Risk levels:

High: CC > 10
Medium: CC 6-10
Low: CC <= 5

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`granularity`	No	Level of detail: 'file', 'type', or 'method' (default: 'file')
`includeDetails`	No	Include per-method breakdown (default: true)

TDQS

A4/5.0

Behavior4/5

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

With no annotations provided, the description carries full burden. It clearly explains the metrics, risk levels, and the prerequisite of load_project. It implies a read-only behavior by simply getting metrics, and the output is described, providing adequate transparency beyond the schema.

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

Conciseness5/5

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

The description is well-structured with sections for purpose, usage, output, metrics, risk levels, and prerequisite. It is concise, front-loaded, and every sentence adds value without redundancy.

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

Completeness4/5

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

Given no output schema and 3 parameters, the description covers the core functionality, input example, metric details, and a prerequisite. It could be improved by explicitly stating the output format (e.g., JSON structure), but the provided details are sufficient for basic usage.

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 new meaning to parameters beyond the schema; it only shows an example usage with filePath. The metrics explanation is helpful but does not clarify granularity or includeDetails.

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 identifies the tool as retrieving cyclomatic complexity, cognitive complexity, and LOC, with a risk assessment. This distinguishes it from sibling analysis tools like analyze_control_flow or analyze_file, which focus on broader or different metrics.

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 includes a usage example and importantly notes that load_project must be called first, which is a key prerequisite. However, it does not explicitly guide when to use this tool over alternatives or when not to use it, leaving some ambiguity.

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

get_dependency_graphA

Get package/type dependencies.

USAGE: get_dependency_graph(scope="type", name="com.example.OrderService") USAGE: get_dependency_graph(scope="package", name="com.example.service") OUTPUT: Dependency graph with nodes and edges

Dependency types tracked:

import: Direct imports
extends: Superclass inheritance
implements: Interface implementation
field: Field type dependencies
parameter: Method parameter types
return: Method return types

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`scope`	Yes	Scope: 'type' or 'package'
`name`	Yes	Type name (fully qualified) or package name
`depth`	No	How deep to follow dependencies (default: 1)
`includeExternal`	No	Include JDK/library dependencies (default: false)

TDQS

A4.2/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It lists tracked dependency types (import, extends, etc.), explains scope and name parameters, and mentions depth and includeExternal defaults. Does not explicitly state read-only nature but implies it.

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?

Description is concise, well-structured with code block examples and bullet list for dependency types. Every sentence adds value, and key information is front-loaded.

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

Completeness4/5

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

Given 4 parameters, no output schema, and no annotations, description covers prerequisites, usage patterns, and tracked dependencies. Does not detail output structure (e.g., 'nodes and edges' is sufficient) but could include example output for 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?

Schema coverage is 100%, so baseline is 3. Description adds value with usage examples for scope and name, and explains dependency types. For depth and includeExternal, it does not add beyond schema but overall improves clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get package/type dependencies' with usage examples, specifying the verb and resource. It distinguishes from siblings like find_circular_dependencies by focusing on general dependency graph retrieval.

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?

Description mentions prerequisite 'Requires load_project to be called first' but provides no guidance on when to use this tool over siblings (e.g., find_circular_dependencies) or when not to use it. No alternatives are explicitly suggested.

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

get_diagnosticsA

Get compilation diagnostics (errors and warnings) for a file or project.

USAGE: get_diagnostics() for all files, or get_diagnostics(filePath="...") for one file OUTPUT: List of compilation errors and warnings with locations

Useful for finding syntax errors, type mismatches, missing imports, etc.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	No	Optional path to source file. If omitted, checks all files.
`severity`	No	Filter by severity: 'error', 'warning', or 'all' (default: 'all')
`maxResults`	No	Max diagnostics to return (default 100)

TDQS

A4.4/5.0

Behavior4/5

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

Although no annotations are provided, the description implies a read-only operation by stating 'Get compilation diagnostics'. It adds important behavioral context: the need for prior load_project, and the output as a list of errors/warnings with locations. No mention of side effects or performance, but sufficient for a 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.

Conciseness5/5

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

The description is concise and well-structured: a one-line purpose, followed by usage examples, output description, use cases, and a prerequisite. Every sentence adds value without redundancy.

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

Completeness4/5

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

The description adequately covers the tool's purpose, usage, and prerequisites. It lacks details on the exact format of returned diagnostics or pagination, but given the schema provides maxResults and no output schema exists, it is sufficiently complete for an agent to use 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 input schema already covers all three parameters with descriptions. The description adds value by showing example usage patterns and clarifying the optional nature of filePath. The severity and maxResults parameters are not elaborated in the description, but the schema handles them sufficiently.

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 retrieves compilation diagnostics (errors and warnings) for a file or project, using a specific verb and resource. It distinguishes itself from sibling analysis tools by focusing on errors and warnings.

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 explicit usage patterns: get_diagnostics() for all files or with a filePath parameter for a specific file. It also mentions the prerequisite of calling load_project first, giving clear context for when to use the tool.

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

get_di_registrationsA

Find all dependency injection registrations in the project.

USAGE: get_di_registrations() OUTPUT: Components, configurations, beans, and injection points

Scans for:

Spring components: @Component, @Service, @Repository, @Controller, @RestController
Configuration: @Configuration
Bean definitions: @Bean
Injection points: @Autowired, @Inject (javax and jakarta)

Returns empty categories for non-Spring projects (does not error).

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`maxResults`	No	Maximum results per annotation type (default 200)

TDQS

A3.9/5.0

Behavior3/5

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

No annotations provided, so description carries burden. It describes scanning behavior and return types, and that it doesn't error on non-Spring projects. However, it does not explicitly state it is a read-only, non-destructive operation, though that is implied.

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

Conciseness4/5

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

Description is well-structured with a purpose statement, usage format, output hint, and a bullet list of scanned items. It is front-loaded and clear, though the bullet list adds some length.

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?

With only one optional parameter and no output schema, the description adequately covers the tool's behavior: it lists scanned annotations, handles non-Spring projects gracefully, and states a prerequisite. The return categories are mentioned, though format is not detailed.

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% for the single parameter maxResults. The description does not add additional context beyond what the schema already provides, so 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 clearly states the tool's purpose as finding all dependency injection registrations, listing specific annotations and injection points. It distinguishes itself from sibling tools, none of which specifically target DI registrations.

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

Usage Guidelines4/5

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

Explicitly notes the prerequisite of calling load_project first, and explains behavior on non-Spring projects (returns empty). While no explicit alternatives are mentioned, the context of sibling tools makes this clear.

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

get_document_symbolsA

Get all symbols (types, methods, fields) in a source file.

USAGE: Provide a file path to get all symbols in that file OUTPUT: Hierarchical list of all types, methods, fields, and nested types

Returns symbols with their locations, kinds, and modifiers.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`includePrivate`	No	Include private members (default true)
`maxResults`	No	Maximum symbols to return (default 500)

TDQS

A4/5.0

Behavior3/5

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

No annotations provided, so description carries full burden. It explains return structure (hierarchical list with locations, kinds, modifiers) and dependency on load_project, but omits error scenarios, performance notes, or read-only nature.

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

Conciseness5/5

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

Three concise sentences plus a usage block. Every sentence contributes purpose, usage, or output details. No wasted text, well front-loaded.

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 3 parameters with full schema, no output schema, and no annotations, the description covers primary functionality and prerequisites well. Minor gaps: could mention maxResults default and error handling for missing file or unloaded project.

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%, baseline 3. Description adds little beyond schema: it restates filePath purpose but does not elaborate on includePrivate or maxResults defaults/behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool retrieves all symbols in a source file, with specific resource and verb. Distinguishes from siblings like get_symbol_info and search_symbols by focusing on the entire file's symbols.

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

Usage Guidelines4/5

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

Explicitly states the prerequisite to call load_project first, which is valuable. Provides usage pattern 'Provide a file path' but lacks explicit exclusions or comparisons to alternative tools.

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

get_enclosing_elementA

Get the enclosing element at a position.

USAGE: Position anywhere in code OUTPUT: Enclosing method, type, and package info

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A3.9/5.0

Behavior3/5

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

No annotations provided; description mentions zero-based coordinates and prerequisite. Lacks detail on return format or edge cases (e.g., what if position is not inside any element). Could be more 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?

Very concise: 5 lines with clear sections (USAGE, OUTPUT, IMPORTANT, requirement). Front-loaded with main purpose, no unnecessary words.

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?

Tool is simple with 3 params and no output schema. Description covers purpose, usage, output type, coordinate system, and prerequisite. Lacks error handling details but still fairly complete for an information retrieval tool.

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

Parameters2/5

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

Schema coverage is 100% and already documents zero-based coordinates. Description merely repeats this information, adding no new semantics 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?

Description clearly states 'Get the enclosing element at a position' and specifies output as enclosing method, type, and package info. It distinguishes from siblings like get_field_at_position and get_method_at_position by being more generic.

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?

Explicit usage instruction ('Position anywhere in code') and prerequisite ('Requires load_project to be called first'). No comparison with alternatives but sufficient for basic usage.

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

get_field_at_positionA

Get field information at a specific position.

USAGE: Position on a field reference or declaration OUTPUT: Field type, modifiers, constant value if applicable

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A4.5/5.0

Behavior4/5

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

Discloses zero-based coordinates and output contents (type, modifiers, constant value). No annotations exist, so description carries full burden; it covers key behavioral traits without contradiction.

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?

Five sentences organized with clear sections (USAGE, OUTPUT, IMPORTANT), no redundant information, and highly efficient.

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

Completeness5/5

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

Given 3 required parameters and no output schema, the description explains inputs, coordinate system, output, and prerequisite. Fully adequate for selecting and invoking 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 descriptions cover all 3 parameters (100% coverage). Description adds value by emphasizing zero-based coordinates and output details, exceeding the baseline of 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 clearly states 'Get field information at a specific position' and specifies usage on a field reference or declaration. This distinguishes it from sibling tools like get_method_at_position and get_type_at_position.

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 explicit usage context: 'Position on a field reference or declaration' and prerequisite 'Requires load_project to be called first.' No exclusion criteria, but sufficient for general use.

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

get_hover_infoA

Get hover information (documentation) for a symbol at a position.

USAGE: Position on any symbol OUTPUT: Signature, Javadoc, and quick info similar to IDE hover

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A4.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 burden. It discloses zero-based coordinates, prerequisite, and output nature (signature, javadoc, quick info). A minor gap: no mention of behavior on invalid positions.

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?

Extremely concise with clear headers (USAGE, OUTPUT, IMPORTANT). Every sentence serves a purpose, no redundancy.

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

Completeness4/5

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

For a simple read tool, covers purpose, usage, output, prerequisite. Lacks details on error handling or empty results, but overall complete for typical use.

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%, baseline 3. Description adds value by explaining coordinates represent a symbol position and that they are zero-based, enhancing semantic understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets hover information (documentation) for a symbol at a position, specifying output as signature, Javadoc, and quick info. It distinguishes from siblings like get_javadoc and get_signature_help by mentioning 'hover' context, and notes zero-based coordinates.

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 explicit usage guidance: 'Position on any symbol' and prerequisite 'Requires load_project to be called first.' However, it does not explicitly compare to similar position-based tools like get_method_at_position.

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

get_http_endpointsA

Assemble the project's HTTP route table.

USAGE: get_http_endpoints() OUTPUT: route -> handler entries (HTTP method, effective path, handler method, framework, location), sorted by path.

Supports:

Spring verb shortcuts: @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping; the class-level @RequestMapping value is composed as the path prefix.
JAX-RS (jakarta.ws.rs and javax.ws.rs): @GET/@POST/... verbs with class-level and method-level @Path composed.

Method-level @RequestMapping(method=...) routes are not assembled; verb-shortcut annotations are the supported Spring form.

Projects without these frameworks return an empty table.

Options:

maxResults: cap the reported endpoints (default 200)

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`maxResults`	No	Maximum endpoints to return (default 200)

TDQS

A4.3/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It discloses prerequisite (load_project), supported frameworks, unsupported annotation forms, default maxResults, and output format. This provides sufficient behavioral context.

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?

Description is well-structured with labeled sections (USAGE, OUTPUT, Supports, Options). It is front-loaded with purpose and efficiently communicates key details without fluff.

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

Completeness5/5

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

For a retrieval tool with no output schema, the description sufficiently explains return format (route->handler entries with details) and limitations (unsupported annotations). It is complete given the tool's complexity.

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%, and description adds minimal value: it restates maxResults parameter with default. Baseline 3 is appropriate as schema already documents the parameter completely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool assembles the project's HTTP route table, with specific verb 'Assemble' and resource 'HTTP route table'. It distinguishes from sibling tools by focusing on HTTP endpoints.

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 mentions that load_project must be called first, and notes that projects without supported frameworks return empty. It also lists unsupported Spring annotations, but does not compare to alternatives.

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

get_javadocA

Get parsed Javadoc documentation for a symbol.

USAGE: Position on any documented symbol OUTPUT: Parsed Javadoc with summary, @param, @return, @throws, etc.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A3.9/5.0

Behavior3/5

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

No annotations, so description carries burden. It mentions zero-based coordinates and prerequisite, adding context. Does not disclose behavior for undocumented symbols or other 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?

Very concise, front-loaded purpose, sections clearly label usage and output. Every sentence is necessary and informative.

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?

Explains output format, prerequisite, and zero-based coordinate system. No output schema, but output description suffices. Good for a moderate-complexity 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% with basic descriptions. Description adds critical context that line and column are zero-based, enhancing parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets parsed Javadoc for a symbol, which is a specific verb+resource. However, it does not differentiate from siblings like get_hover_info or get_symbol_info.

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 clear usage: position on documented symbol and prerequisite (load_project). Lacks explicit when-not-to-use or alternatives.

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

get_jpa_modelA

Assemble the project's JPA entity model.

USAGE: get_jpa_model() OUTPUT: Entities with table name, id field, and relationships (kind, target entity, mappedBy side), with locations.

Scans @Entity types (jakarta.persistence and javax.persistence) and reads @Table, @Id, and @OneToMany/@ManyToOne/@OneToOne/ @ManyToMany field annotations. Relationship targets are resolved from the field's type binding, including through collection type arguments (List -> Order).

Projects without JPA on the classpath return an empty model.

Options:

maxResults: cap the reported entities (default 100)

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`maxResults`	No	Maximum entities to return (default 100)

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description fully discloses scanning behavior (Entity, Table, Id, relationships), target resolution method, and empty model for non-JPA projects. No contradictions.

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

Conciseness5/5

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

The description is well-structured with usage, output, scanning details, and prerequisites. Every sentence adds value without redundancy.

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

Completeness5/5

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

Given no output schema, the description adequately describes the output (entities with table name, id, relationships, locations). It covers prerequisites, parameter default, and edge cases.

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% and the parameter description already includes the default value. The tool description repeats this info without adding new 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 it assembles the JPA entity model, specifies the output includes tables, IDs, and relationships, and distinguishes it from sibling tools by focusing on JPA entities.

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 explicitly states the prerequisite 'Requires load_project to be called first' and notes behavior when JPA is absent. It lacks explicit comparison to alternatives but the tool is unique enough.

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

get_method_at_positionA

Get method information at a specific position.

USAGE: Position on a method reference or declaration OUTPUT: Method signature, parameters, return type, modifiers, exceptions

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A4.5/5.0

Behavior4/5

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

Emphasizes zero-based coordinates and load_project dependency. Lacks explicit statement about read-only nature, but the purpose implies no 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?

Well-structured with clear sections, no wasted words, and front-loaded important information (purpose and usage).

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?

Describes output fields (signature, parameters, etc.) despite no output schema, and covers all necessary context for a simple positional lookup 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%, but description adds value by mentioning zero-based coordinates for line and column, which is critical for correct usage.

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?

Specific verb 'Get' and resource 'method information at a specific position', clearly distinguishing from sibling tools like get_field_at_position or get_type_at_position.

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?

States usage on 'method reference or declaration' and prerequisite 'load_project', but does not explicitly exclude cases where other tools (e.g., get_type_at_position) would be preferred.

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

get_project_structureA

Get project structure showing package hierarchy.

USAGE: Call to see the package tree of the loaded project OUTPUT: Source roots with packages and file counts

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`includeFiles`	No	Include file names in each package (default false)
`maxDepth`	No	Maximum package depth to show (default 10)

TDQS

A4.2/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It reveals the tool is a read operation showing package hierarchy with file counts and requires a prerequisite. Does not mention rate limits or side effects, but behavior is straightforward.

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

Conciseness5/5

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

Three sentences, front-loaded with main action. USAGE and OUTPUT sections are efficient. No redundant or extraneous 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?

Given no output schema, description explains output as 'Source roots with packages and file counts'. Covers prerequisite. Sufficient for a simple tool with only two optional parameters and full schema documentation.

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 parameters have descriptions. The tool description does not add additional meaning beyond the schema, so baseline 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?

Description clearly states 'Get project structure showing package hierarchy' and specifies output as 'Source roots with packages and file counts'. It distinguishes from sibling tools like get_type_hierarchy or get_dependency_graph.

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?

States 'USAGE: Call to see the package tree of the loaded project' and explicitly requires 'load_project to be called first'. Provides explicit context but doesn't mention alternatives or when not to use.

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

get_quick_fixesA

List available fixes for a problem at position.

USAGE: get_quick_fixes(filePath="...", line=10) OUTPUT: List of quick fixes with fixId, label, and category

Supported fixes:

UndefinedType: Suggest imports for unresolved types
UnusedImport: Remove unused import
UnhandledException: Add throws or surround with try-catch

IMPORTANT: Uses ZERO-BASED line numbers.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	No	Zero-based column number (optional, uses whole line if omitted)

TDQS

A4.2/5.0

Behavior4/5

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

Given no annotations, the description discloses zero-based line numbers and the prerequisite. It describes the output format. It does not explicitly state that the tool is read-only, which is a minor gap.

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 and well-structured: purpose, usage example, output format, list of supported fixes, important note, and prerequisite. Every sentence adds value with no redundancy.

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

Completeness4/5

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

The description covers purpose, usage, output, supported fixes, and prerequisite. It lacks details on error handling or behavior when no fixes exist, but given the tool's simplicity, it is mostly complete.

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 all parameters described. The description adds the usage example but does not provide significant meaning beyond what the schema already provides (e.g., zero-based is already in 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 lists available fixes for a problem at a position, with verb 'list' and resource 'fixes'. It distinguishes from sibling tools like 'apply_quick_fix' which applies a fix, and 'get_diagnostics' which provides problems.

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 a usage example and explicitly states the prerequisite ('Requires load_project to be called first'). It lists supported fix categories, guiding agent on when to use. However, it does not explicitly mention when not to use or provide alternatives.

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

get_signature_helpA

Get method signature help at a position.

USAGE: Position on a method call or declaration OUTPUT: Method signatures with parameter info

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A4.5/5.0

Behavior5/5

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

Despite no annotations, the description clearly states the output type (method signatures with parameter info) and the zero-based coordinate system, which is a critical behavioral detail for correct invocation.

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?

Extremely concise with a clear structure: line for purpose, bullet for usage, line for output, important note, and prerequisite. Every sentence adds value with no redundancy.

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

Completeness5/5

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

For a signature help tool with no output schema, the description adequately covers input context (zero-based coordinates, prerequisite), output expectation (signatures with param info), and usage context. No missing critical information.

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% with each parameter clearly documented. The description adds no additional semantic value beyond reiterating zero-based coordinates (already in schema). Baseline score 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?

Clearly states the tool retrieves method signature help at a given position, and specifies it is for method calls or declarations, distinguishing it from sibling tools like get_hover_info or get_method_at_position.

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 explicit usage context (position on method call/declaration) and a critical prerequisite (load_project). Does not discuss alternatives or when to avoid, but the usage is well-scoped.

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

get_super_methodA

Find the method that this method overrides or implements.

USAGE: Position on a method that overrides/implements another OUTPUT: The superclass/interface method being overridden

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A4.4/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. Discloses zero-based coordinates and prerequisite. Does not detail side effects or output format, but adequats for a query 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?

Very concise with clear sections (USAGE, OUTPUT, IMPORTANT). No wasted words, essential information front-loaded.

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 no output schema, describes output as 'superclass/interface method'. Lacks specific return structure, but sufficient for a simple query tool among many siblings.

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 has 100% coverage with descriptions. Adds value by stating coordinates are zero-based, clarifying expected input 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?

Clearly states it finds the super method overridden/implemented by a given method. Differentiates from siblings like 'find_implementations' by specifying the exact relationship.

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

Usage Guidelines4/5

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

Explicitly instructs to position on a method that overrides/implements, and mentions prerequisite load_project. Lacks explicit when-not-to-use but provides clear context.

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

get_symbol_infoA

Get detailed information about any symbol at a position.

USAGE: Position on any symbol (type, method, field, variable) OUTPUT: Comprehensive info including kind, modifiers, signature, location

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It reveals that the tool uses zero-based coordinates and requires load_project. It also summarizes output content ('kind, modifiers, signature, location'), providing insight into behavior beyond a simple fetch.

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 brief yet comprehensive, using clear sections (USAGE, OUTPUT, IMPORTANT) without redundancy. Every sentence adds value, making it easy for an AI agent to parse.

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

Completeness5/5

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

Given no output schema and three parameters, the description covers purpose, usage, output summary, coordinate system, and prerequisite. There are no obvious gaps for an information retrieval tool of this complexity.

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%, but the description adds critical meaning by highlighting that coordinates are zero-based. This is essential for correct parameter usage and goes beyond the schema's basic descriptions.

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 'Get' and the resource 'detailed information about any symbol at a position', distinguishing it from similar tools like get_type_at_position or get_method_at_position. It specifies that it works on any symbol (type, method, field, variable).

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 explicit usage instructions: 'Position on any symbol (type, method, field, variable)', notes coordinate system ('Uses ZERO-BASED coordinates'), and states prerequisite 'Requires load_project to be called first'. It does not explicitly compare with siblings but gives sufficient context for correct use.

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

get_type_at_positionA

Get type information at a specific position.

USAGE: Position on a type reference or declaration OUTPUT: Type details including kind, modifiers, superclass, interfaces

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A3.5/5.0

Behavior3/5

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

With no annotations provided, the description carries full transparency burden. It discloses zero-based coordinates and the need for a loaded project, but does not specify error behavior (e.g., if the position is not on a type) or side effects. Output details are partially mentioned.

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

Conciseness4/5

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

The description is concise (3 sentences) and well-structured with headings (USAGE, OUTPUT, IMPORTANT). It gets to the point quickly, though the OUTPUT section could be integrated into the main sentence for further brevity.

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 lack of output schema, the description usefully lists output fields (kind, modifiers, superclass, interfaces). It covers usage context and prerequisites. However, missing details on error handling and edge cases prevent a higher score.

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 has 100% coverage, with descriptions for filePath, line, column including 'Zero-based' in the line and column descriptions. The tool description reiterates zero-based coordinates but adds no significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get type information at a specific position.' It positions itself as a position-aware type query tool, distinct from tools like get_type_hierarchy or get_type_members, but does not explicitly differentiate from similar position-based tools like get_field_at_position or get_method_at_position.

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 provides a usage hint ('Position on a type reference or declaration') and a prerequisite ('Requires load_project to be called first'). However, it lacks guidance on when not to use this tool versus alternatives. No exclusions or alternatives are mentioned.

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

get_type_hierarchyA

Get the type hierarchy (supertypes and subtypes) for a Java type.

USAGE: Position on a type, returns full inheritance chain OUTPUT: Superclasses, interfaces, and all subtypes

Can be called with either:

File position (filePath, line, column) - finds type at cursor
Type name (typeName) - looks up type by qualified name

IMPORTANT: Uses ZERO-BASED coordinates when using file position.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	No	Path to source file (for position-based lookup)
`line`	No	Zero-based line number
`column`	No	Zero-based column number
`typeName`	No	Fully qualified type name (alternative to position)
`maxDepth`	No	Maximum depth of hierarchy to return (default 10)

TDQS

A4.4/5.0

Behavior4/5

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

No annotations provided, but description discloses key behavioral traits: zero-based coordinates, requirement to have loaded project, and output content (superclasses, interfaces, subtypes). Clearly a read operation with no contradictions.

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

Conciseness5/5

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

Concise but complete: two sentences for purpose, followed by structured USAGE, OUTPUT, modes, important note, and prerequisite. Every sentence adds necessary information without redundancy.

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

Completeness4/5

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

Given no output schema and no annotations, the description adequately covers prerequisites, coordinate system, and invocation modes. Could be more specific about the structure of the returned hierarchy, but it's sufficient for an agent to understand the tool's behavior.

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?

Input schema covers all 5 parameters with descriptions. Description adds context: clarifies zero-based coordinates for line/column, default maxDepth=10, and distinguishes position-based vs typeName lookup. Adds value beyond 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?

Clearly states it retrieves type hierarchy (supertypes and subtypes) for a Java type, using a specific verb+resource. Distinguishes from siblings like 'get_type_at_position' and 'get_type_members' by focusing on inheritance chain.

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 explicit usage instructions: two modes (file position or type name), prerequisite (load_project), and coordinate system. However, does not include when-not-to-use guidance or alternatives.

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

get_type_membersA

Get all members (methods, fields, nested types) of a specific type.

USAGE: Provide a type name to get all its members OUTPUT: Lists of methods, fields, and nested types with their details

Options:

includeInherited: Also include members from superclasses/interfaces
memberKind: Filter to "method", "field", or "type" only

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`typeName`	Yes	Fully qualified or simple type name
`includeInherited`	No	Include inherited members (default false)
`memberKind`	No	Filter: 'method', 'field', 'type', or null for all

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description must disclose behavioral traits. It explains that the tool returns lists of members with details and mentions options. However, it does not discuss side effects, performance implications, or whether the tool modifies state. The description is adequate 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?

The description is concise and well-structured with clear sections for USAGE, OUTPUT, and Options. Every sentence earns its place without unnecessary verbosity.

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 main functionality, includes a prerequisite, and summarizes output. However, it lacks details about the output format (what 'details' are included) and could mention whether the response is paginated or has size limits. Overall, it is fairly complete for a query 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?

The input schema has 100% coverage, so the baseline is 3. The description adds value by explaining the effects of 'includeInherited' and 'memberKind' options and reiterating the prerequisite, providing context 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 retrieves members (methods, fields, nested types) of a specific type. It uses a specific verb ('Get') and resource ('members of a specific type'), and the purpose is distinguishable from sibling tools like 'analyze_type'.

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 provides a prerequisite ('Requires load_project to be called first') and describes options. However, it does not specify when to use this tool versus alternatives like 'analyze_type' or 'get_type_hierarchy', nor does it give guidance on 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.

get_type_usage_summaryA

Get comprehensive usage summary for a type across the codebase.

USAGE: get_type_usage_summary(typeName="com.example.Foo") OUTPUT: Instantiations, casts, instanceof checks, type arguments, annotations

Aggregates all usage patterns in a single call:

Instantiations (new Foo())
Casts ((Foo) x)
Instanceof checks (x instanceof Foo)
Type arguments (List)
Annotation usages (if annotation type)

Use this to understand how a type is used throughout the project.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Fully qualified or simple type name
`maxPerCategory`	No	Maximum results per category (default 10)

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries full burden and discloses the output categories (instantiations, casts, instance of, etc.) and the aggregating nature. It does not mention read-only or performance, but the output description is sufficient for understanding behavior.

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

Conciseness4/5

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

The description is well-structured with a usage line, output list, and bullet points. It is informative without being excessively long, though the bullet list could be integrated more concisely.

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?

No output schema exists, so the description's enumeration of return categories (instantiations, casts, etc.) is necessary and adequate. It also covers prerequisites, making it fairly complete for a multi-category analysis 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 coverage is 100%, so baseline 3. The description adds a usage example but no new meaning beyond the schema's parameter descriptions. The example is helpful but not necessary.

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 aggregates all usage patterns for a type, listing exact categories (instantiations, casts, instanceof, type arguments, annotations). This distinguishes it from sibling tools like find_casts or find_type_instantiations, which are single-purpose.

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 explicit guidance with 'Use this to understand how a type is used throughout the project' and a prerequisite ('Requires load_project to be called first'). It implies this is the aggregate version over siblings but does not explicitly state 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.

go_to_definitionA

Navigate to symbol definition.

USAGE: Position cursor on a symbol reference, returns definition location. OUTPUT: File path, line, column of the definition.

IMPORTANT: Uses ZERO-BASED coordinates. If editor shows 'Line 14, Column 5', pass line=13, column=4

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file (absolute or relative to project)
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number

TDQS

A4.2/5.0

Behavior3/5

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

No annotations provided, so description bears full burden. Discloses zero-based coordinates and prerequisite, but does not mention error handling (e.g., if symbol not found) or read-only nature.

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?

Very concise, with bullet-like structure. Each sentence adds necessary information. No wasted words.

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?

No output schema, but description explains return values (file path, line, column) and includes zero-based hint. Missing error behavior, but overall fairly complete for a simple navigation 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 has 100% coverage with descriptions. Description adds value by explaining zero-based context and that filePath can be absolute or relative, which clarifies usage beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Navigate to symbol definition', which is a specific verb and resource. It distinguishes from siblings like 'find_references' by focusing on definition location.

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 explicit usage: position cursor, returns definition location. Mentions prerequisite 'load_project' and zero-based coordinates. Lacks explicit when-not-to-use, but purpose is narrow enough.

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

health_checkA

Check server status and project state.

USAGE: Call on startup to verify server is operational. OUTPUT: Server status, project info if loaded, capabilities.

WORKFLOW:

Call health_check to verify server is running
If no project loaded, call load_project next
Use returned capabilities to understand available features

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.9/5.0

Behavior5/5

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

No annotations provided, so description carries full burden. It describes output (server status, project info, capabilities) and implies read-only health check behavior, which is appropriate.

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

Conciseness5/5

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

Three concise sentences plus a structured workflow list. Purpose is front-loaded, every sentence adds value, no redundancy.

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

Completeness5/5

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

For a simple health check tool with no params and no output schema, the description fully covers purpose, usage, workflow, and 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?

No parameters exist (0 params, 100% schema coverage), so baseline 4. Description doesn't need to add param info, and it doesn't miss any.

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 'Check server status and project state.' and specifies 'Call on startup to verify server is operational.' This distinguishes it from all sibling tools which focus on code analysis/refactoring.

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 saying 'Call on startup' and providing a workflow (1. health_check, 2. load_project if needed) gives clear when-to-use and next steps.

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

inline_methodA

Inline a method call by replacing it with the method body.

Returns the text edit needed to inline the method call. The caller should apply this edit to perform the inlining.

USAGE: Position cursor on a method call OUTPUT: Edit to replace call with method body

IMPORTANT: Uses ZERO-BASED coordinates.

LIMITATIONS:

Method must be in the same project (source available)
Works best with simple methods (no complex control flow)
Single return statement is handled, multiple returns may need review

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the method call
`line`	Yes	Zero-based line number of method call
`column`	Yes	Zero-based column number (on method name)

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations provided, the description fully describes behavioral aspects: it returns an edit to be applied, uses zero-based coordinates, and lists limitations. This gives the agent a clear understanding of what to expect.

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 and well-structured: purpose, usage, output, important note, limitations, prerequisite. Every sentence adds value, and key information is front-loaded.

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 purpose, usage, output, limitations, and prerequisites. It lacks details on error handling or edge cases, but for a refactoring tool with no output schema, it is sufficiently 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?

Input schema has 100% coverage, but the description adds valuable context: zero-based coordinates and that column refers to the method name. This goes beyond the schema's field descriptions.

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 inlines a method call by replacing it with the method body, distinguishing it from siblings like inline_variable which handle variables. The verb 'inline' and resource 'method call' are specific and unambiguous.

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

Usage Guidelines4/5

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

The description provides explicit usage instructions ('Position cursor on a method call') and prerequisites ('Requires load_project to be called first'). Limitations are stated (same project, simple methods) but alternative tools like inline_variable are not mentioned.

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

inline_variableA

Inline a local variable by replacing all usages with its initializer expression.

Returns the text edits needed to inline the variable. The caller should apply these edits to perform the inlining.

USAGE: Position cursor on variable declaration or usage OUTPUT: Edits to delete declaration and replace usages with initializer

IMPORTANT: Uses ZERO-BASED coordinates. SAFETY: Will refuse if variable is modified after initialization.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file
`line`	Yes	Zero-based line number of variable declaration or usage
`column`	Yes	Zero-based column number

TDQS

A4.1/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. Includes safety check (refuses if variable modified after init), zero-based coordinate reminder, and states that edits need to be applied. Discloses key behavioral traits beyond basic function.

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?

Extremely concise: three short paragraphs with clear headings. First sentence immediately states primary action. Every sentence adds necessary information with no redundancy.

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

Completeness4/5

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

Covers all critical aspects: prerequisite (load_project), coordinate system, safety condition, and return type (text edits). No output schema, but return type is described. Minor gap: could mention if edits are a list or single, but not essential.

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% but description adds value by clarifying that line and column reference cursor position on variable declaration or usage, and reminding of zero-based coordinates. This aids correct parameter population.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool inlines a local variable by replacing usages with initializer, returning text edits. Distinguished from similar siblings like extract_variable by specifying the action of replacing usages.

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 explicit usage instructions: position cursor on declaration or usage, requires load_project first, and mentions safety refusal condition. Lacks explicit 'when not to use' but gives sufficient context for correct invocation.

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

introduce_parameter_objectA

Bundle a method's parameters into a new parameter-object class and rewrite the method and all callers to use it. The class is generated as a member of the declaring type.

USAGE: Position on the method name; optionally name the class and parameter. OUTPUT: editsByFile with all required edits; warnings from JDT's condition checking. Edits are returned as text - apply them yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the method
`line`	Yes	Zero-based line number of the method declaration
`column`	Yes	Zero-based column number (on the method name)
`className`	No	Name for the parameter-object class (default: <MethodName>Parameters)
`parameterName`	No	Name for the new parameter (default: parameterObject)

TDQS

A4.1/5.0

Behavior3/5

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

No annotations provided, so description must disclose behavior. It mentions zero-based coordinates, return format (editsByFile), and JDT warnings. However, it does not explicitly state that the tool modifies files (though it returns edits for manual application) or clarify destructive nature. Adequate but missing important safety context.

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

Conciseness4/5

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

Description is concise with separate sections for usage, output, and important notes. No filler sentences, but the structure is slightly fragmented. Still earns its space.

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 complex refactoring tool with no output schema, the description covers key aspects: what it does, how to invoke (position), output format, important coordinate system, and prerequisite. Reasonably 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?

Schema coverage is 100% with descriptions for each parameter. The description adds value by clarifying that line/column are zero-based, column is on method name, and providing default names for className and parameterName. This goes beyond schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool bundles method parameters into a new class and rewrites method and callers. The verb 'bundle' and resource 'parameter-object class' are specific, and the description distinguishes it from sibling refactoring tools like extract_method or change_method_signature.

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 explicit usage instructions: position on method name, optionally name class/parameter, and requires load_project first. Lacks explicit when-not-to-use or alternative tool references, but context from sibling list helps.

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

load_projectA

Load a Java project for analysis. MUST be called before using other analysis tools.

USAGE: load_project(projectPath="/path/to/project") OUTPUT: Project structure summary including packages, source files, build system

Supports:

Maven projects (pom.xml)
Gradle projects (build.gradle or build.gradle.kts)
Plain Java projects with src/ directory

WORKFLOW:

Call load_project with absolute path to project root
Wait for project to load (may take a few seconds for large projects)
Use health_check to verify project is loaded
Begin using analysis tools (search_symbols, find_references, etc.)

SYNC (strict mode): answers are always verified against the files on disk - no reload is needed after editing, adding, or deleting source files. Call load_project only on first use, when a response reports RELOAD_REQUIRED (a build file changed), or to rebuild everything from scratch.

ParametersJSON Schema

Name	Required	Description	Default
`projectPath`	Yes	Absolute path to the project root directory containing pom.xml or build.gradle

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description fully covers behavior: loading process, potential delay, SYNC mode for disk verification, and when reload is needed. Could add more on internal state changes.

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

Conciseness4/5

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

Well-structured with sections and bullet points, front-loaded with key info. Slightly verbose but every sentence contributes; could tighten redundancy.

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

Completeness5/5

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

Comprehensive for a setup tool: describes output format, workflow, SYNC semantics, and when to call. No output schema but description compensates adequately.

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

Parameters5/5

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

Even though schema covers 100%, the description adds value with an example usage, clarifies 'absolute path', and lists supported project types. This goes beyond schema basics.

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 'Load a Java project for analysis' and establishes it as a prerequisite for other tools, distinguishing it from siblings by its unique initialization role.

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 'MUST be called before using other analysis tools' and provides a workflow with steps, when to call (first use, RELOAD_REQUIRED, rebuild), and references alternatives like health_check.

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

move_type_to_new_fileA

Move a member (nested) type into its own top-level file. Non-static member types gain a field referencing the former enclosing instance.

USAGE: Position on the nested type's name. OUTPUT: createdFiles carries the new top-level file content; editsByFile carries the enclosing file's edits. Nothing is written - create the file and apply the edits yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the nested type
`line`	Yes	Zero-based line number of the nested type declaration
`column`	Yes	Zero-based column number (on the type name)

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, the description fully discloses key behaviors: non-static member types gain a field referencing the former enclosing instance, output format (createdFiles, editsByFile), zero-based coordinates, and that nothing is written. This sufficiently informs the agent of side effects and preconditions.

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

Conciseness4/5

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

The description is well-structured with labeled sections (USAGE, OUTPUT, IMPORTANT) and front-loads the main action. Every sentence adds value, though it could be slightly tighter (e.g., combining coordinate details).

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 refactoring tool with no output schema, the description explains the return fields and behavior (file creation not automatic). It covers prerequisites and coordinate system. Some edge cases (e.g., already top-level type) are not addressed, but overall it is complete enough.

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% with descriptions for all three parameters. The description adds critical context: 'Uses ZERO-BASED coordinates' and 'Position on the nested type's name,' which clarifies how to set 'line' and 'column' beyond the schema's generic descriptions.

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 clearly 'Move a member (nested) type into its own top-level file.' It uses a specific verb 'Move' and resource 'type', and the context of being a refactoring operation distinguishes it from sibling tools like 'analyze_type' or 'get_type_hierarchy'.

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 explicit usage instructions: 'Position on the nested type's name' and 'Requires load_project to be called first.' It explains the output structure and the need to manually create files, giving clear context on when and how to use. Does not explicitly state when not to use, but the purpose is well-defined.

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

organize_importsA

Organize imports in a Java file.

Removes unused imports and sorts remaining imports alphabetically. Returns the organized import block that should replace the existing imports.

USAGE: organize_imports(filePath="path/to/File.java") OUTPUT: Organized import statements and list of changes

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	Yes	Path to source file

TDQS

A3.8/5.0

Behavior3/5

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

Describes the action (remove unused, sort) and output (organized block and changes), but does not fully disclose whether the file is modified directly or if permissions are needed. No annotations are provided to supplement.

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

Conciseness4/5

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

The description is concise and front-loaded with the main action. It includes a usage example, output description, and prerequisite without redundancy.

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?

Sufficient for a simple tool with one parameter and clear output, but lacks details on error handling or edge cases. No output schema is provided, but the description explains the return value.

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 single parameter 'filePath' has a schema description of 'Path to source file', and the description adds no additional semantics. With 100% schema coverage, 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 clearly states the tool organizes imports in a Java file by removing unused imports and sorting alphabetically. It distinguishes from sibling tools like 'suggest_imports' by focusing on organization rather than suggestion.

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 a usage example and explicitly requires 'load_project' to be called first. It does not mention when not to use it or alternatives, but the context is clear.

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

pull_upA

Pull a method or field up into the superclass and remove it from the declaring subclass.

USAGE: Position on the member name in the subclass. OUTPUT: editsByFile covering the superclass (member added) and the subclass (member removed); warnings from JDT's condition checking. Edits are returned as text - apply them yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the member
`line`	Yes	Zero-based line number of the member declaration
`column`	Yes	Zero-based column number (on the member name)

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description fully discloses behavioral traits: output structure (editsByFile covering superclass and subclass), warnings from condition checking, and that edits are returned as text (not automatically applied). Also notes zero-based coordinates, which is important for correct invocation.

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

Conciseness4/5

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

The description is structured with clear sections (purpose, usage, output, important note) and is front-loaded with the main action. It is concise with only necessary details, though 'USAGE' and 'OUTPUT' could be slightly condensed.

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 what the tool does, how to use it (positioning), prerequisites (load_project), output format, and the need to manually apply edits. No output schema exists, but the text description suffices for an agent to understand the consequences.

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%, but the description adds value by clarifying the coordinate system ('Uses ZERO-BASED coordinates') and the semantic meaning of line and column ('Position on the member name in the subclass'), which is beyond the schema descriptions.

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 ('Pull a method or field up into the superclass') and the effect ('remove it from the declaring subclass'). It specifies the resource (superclass) and distinguishes from related tools like 'push_down' implicitly through the naming.

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 explicit usage instruction: 'Position on the member name in the subclass.' and prerequisite: 'Requires load_project to be called first.' Lacks explicit when-not-to-use or alternatives, but the 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.

push_downA

Push a method or field down into the declaring class's subclasses and remove it from the declaring class.

USAGE: Position on the member name in the superclass. OUTPUT: editsByFile covering the superclass (member removed) and each subclass (member added); warnings from JDT's condition checking. Edits are returned as text - apply them yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the member
`line`	Yes	Zero-based line number of the member declaration
`column`	Yes	Zero-based column number (on the member name)

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description fully discloses output format (editsByFile with warnings), that edits are returned as text (not applied), and the use of zero-based coordinates. It covers prerequisites and behavioral context well.

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 brief yet comprehensive, front-loading purpose, usage, output, and important notes. Every sentence adds value with no redundancy.

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

Completeness4/5

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

The description explains output and prerequisites adequately for a refactoring tool without an output schema. It could mention type hierarchy requirements but is largely complete.

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 descriptions. The description adds minimal additional meaning beyond reinforcing zero-based coordinates and the 'member name' context; nothing significantly new is provided.

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 pushes a method or field down into subclasses and removes it from the superclass, using specific verbs and resources. This distinguishes it from siblings like pull_up or extract_superclass.

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 usage instructions ('Position on the member name in the superclass') and a prerequisite ('Requires load_project to be called first'), but does not explicitly compare to alternatives or state when not to use.

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

rename_symbolA

Rename a symbol (variable, method, field, class, etc.) across the project.

Returns text edits for all occurrences that need to be changed. The caller should apply these edits to perform the rename.

USAGE: Position on symbol, provide new name OUTPUT: List of text edits to apply

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	Yes	Path to source file containing the symbol
`line`	Yes	Zero-based line number
`column`	Yes	Zero-based column number
`newName`	Yes	New name for the symbol

TDQS

A4/5.0

Behavior4/5

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

Discloses zero-based coordinates and that it returns text edits to be applied by caller. With no annotations, this covers key behaviors adequately.

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?

Description is concise with three short sentences, front-loaded with purpose. No superfluous 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?

Explains return type (text edits) and coordinate system. Lacks error scenarios but sufficient for typical refactoring tool. No output schema needed.

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%; description essentially restates schema parameters without adding new meaning beyond usage 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?

Description clearly states 'Rename a symbol' with explicit resource types. Differentiates from siblings as no other rename tool exists.

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?

Provides basic usage instructions and prerequisite (load_project), but no guidance on when to use vs alternatives or when not to use.

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

search_symbolsA

Search for types, methods, fields by name pattern. Supports glob patterns: * (any chars), ? (single char)

USAGE: search_symbols(query="*Service", kind="class") OUTPUT: List of matching symbols with locations

EXAMPLES:

search_symbols(query="Order*") - classes starting with Order
search_symbols(query="*Repository", kind="interface")
search_symbols(query="get*", kind="method")

PAGINATION: Use offset parameter for large result sets

IMPORTANT: Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search pattern - supports * and ? wildcards
`kind`	No	Filter by kind: class, interface, enum, method, field
`maxResults`	No	Max results to return (default 50)
`offset`	No	Skip first N results for pagination

TDQS

A4.5/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. Discloses glob patterns, pagination, and output (list of symbols with locations). Does not mention performance or limits, but overall sufficient.

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

Conciseness5/5

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

Well-structured with clear sections: purpose, glob support, usage line, examples, pagination, prerequisite. Every sentence adds value, no redundancy.

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

Completeness5/5

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

Despite no output schema or annotations, the description covers all necessary aspects: search criteria, usage patterns, pagination, and prerequisite. Complete for an agent to use 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?

Schema coverage is 100%, and description adds value with usage examples and specific glob patterns. Goes beyond schema by demonstrating how parameters are used together.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Search for types, methods, fields by name pattern', specifying the verb (Search) and resource (symbols by name). Distinct from siblings like find_references and get_symbol_info, which serve 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?

Provides explicit prerequisite ('Requires load_project to be called first'), examples, and pagination info. Does not explicitly mention when not to use or alternatives, but the context is clear.

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

suggest_importsA

Find import candidates for unresolved type.

USAGE: suggest_imports(typeName="List") OUTPUT: List of matching types with fully qualified names and relevance

Searches project sources, JDK, and libraries for types matching the simple name. Results are sorted by relevance (java.util types ranked higher than java.awt, etc.).

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description	Default
`typeName`	Yes	Simple type name to find imports for (e.g., 'List', 'Map')
`maxResults`	No	Maximum candidates to return (default 20)

TDQS

A4.2/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It details search scope (project sources, JDK, libraries) and sorting by relevance, which is good behavioral disclosure.

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

Conciseness5/5

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

Concise and well-structured: purpose, example, output description, search details, prerequisite. No wasted sentences.

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 2-param tool with no output schema and no annotations, the description adequately covers purpose, usage, search scope, and sorting. Could optionally note default maxResults.

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 baseline is 3. Description only adds a usage example for 'typeName' but no additional meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Find import candidates for unresolved type' and provides a usage example. It is distinct from siblings like 'organize_imports' or 'find_references'.

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

Usage Guidelines4/5

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

Explicitly requires 'load_project' to be called first. Usage example is provided, but no explicit when-not-to-use or alternatives are mentioned.

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

validate_syntaxA

Quick syntax-only validation for a file or inline code.

USAGE: validate_syntax(filePath="...") or validate_syntax(content="...") OUTPUT: Syntax errors (no semantic analysis for speed)

Much faster than get_diagnostics - use for quick syntax checks.

Requires load_project to be called first.

ParametersJSON Schema

Name	Required	Description
`filePath`	No	Path to source file to validate
`content`	No	Inline Java source code to validate (alternative to filePath)
`fileName`	No	Optional filename for inline content (default: Untitled.java)

TDQS

A4.6/5.0

Behavior4/5

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

Discloses no semantic analysis and output type (Syntax errors), but lacks details on error format. No annotations provided, so description carries burden; the disclosure is adequate.

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?

Four sentences, front-loaded with purpose, every sentence earns its 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?

Covers purpose, usage, prerequisite, and output nature well for a simple tool, but could briefly mention return type or format.

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%, baseline 3. Description adds usage examples and optional filename context, adding value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Quick syntax-only validation' for file or inline code, differentiating from siblings like get_diagnostics.

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

Usage Guidelines5/5

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

Explicitly says 'Use for quick syntax checks', contrasts with get_diagnostics for semantic analysis, and notes prerequisite load_project.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv1.5.0Jun 12, 2026

Changedanalyze_change_impact2 fields changed

addedInput schema / properties / maxResults

Added value: +{
+  "description": "Cap on affectedMethods in transitive mode (default 200)",
+  "type": "integer"
+}

addedInput schema / properties / transitive

Added value: +{
+  "description": "Full reverse closure over the project graph, no depth ceiling (default false)",
+  "type": "boolean"
+}

Changedanalyze_data_flow2 fields changed

addedInput schema / properties / followCalls

Added value: +{
+  "description": "Track null/taint facts across method calls (default false)",
+  "type": "boolean"
+}

addedInput schema / properties / maxCallDepth

Added value: +{
+  "description": "Call-edge bound for followCalls (default 2, min 1)",
+  "type": "integer"
+}

Addedfind_affected_tests
Addedfind_unreachable_code
Addedget_http_endpoints
Addedget_jpa_model

8 tool updatesv1.4.1Jun 10, 2026
- Addedapply_cleanup
- Addeddiagnose_and_fix
- Addedencapsulate_field
- Addedextract_superclass
- Addedintroduce_parameter_object
- Addedmove_type_to_new_file
- Addedpull_up
- Addedpush_down
63 tool updatesv1.3.4May 26, 2026
- Addedanalyze_change_impact
- Addedanalyze_control_flow
- Addedanalyze_data_flow
- Addedanalyze_file
- Addedanalyze_method
- Addedanalyze_type
- Addedapply_quick_fix
- Addedchange_method_signature
- Addedconvert_anonymous_to_lambda
- Addedextract_constant
- Addedextract_interface
- Addedextract_method
- Addedextract_variable
- Addedfind_annotation_usages
- Addedfind_casts
- Addedfind_catch_blocks
- Addedfind_circular_dependencies
- Addedfind_field_writes
- Addedfind_implementations
- Addedfind_instanceof_checks
- Addedfind_large_classes
- Addedfind_method_references
- Addedfind_naming_violations
- Addedfind_possible_bugs
- Addedfind_references
- Addedfind_reflection_usage
- Addedfind_tests
- Addedfind_throws_declarations
- Addedfind_type_arguments
- Addedfind_type_instantiations
- Addedfind_unused_code
- Addedget_call_hierarchy_incoming
- Addedget_call_hierarchy_outgoing
- Addedget_classpath_info
- Addedget_complexity_metrics
- Addedget_dependency_graph
- Addedget_di_registrations
- Addedget_diagnostics
- Addedget_document_symbols
- Addedget_enclosing_element
- Addedget_field_at_position
- Addedget_hover_info
- Addedget_javadoc
- Addedget_method_at_position
- Addedget_project_structure
- Addedget_quick_fixes
- Addedget_signature_help
- Addedget_super_method
- Addedget_symbol_info
- Addedget_type_at_position
- Addedget_type_hierarchy
- Addedget_type_members
- Addedget_type_usage_summary
- Addedgo_to_definition
- Addedhealth_check
- Addedinline_method
- Addedinline_variable
- Addedload_project
- Addedorganize_imports
- Addedrename_symbol
- Addedsearch_symbols
- Addedsuggest_imports
- Addedvalidate_syntax
63 tool updatesv1.3.3May 24, 2026
- Removedanalyze_change_impact
- Removedanalyze_control_flow
- Removedanalyze_data_flow
- Removedanalyze_file
- Removedanalyze_method
- Removedanalyze_type
- Removedapply_quick_fix
- Removedchange_method_signature
- Removedconvert_anonymous_to_lambda
- Removedextract_constant
- Removedextract_interface
- Removedextract_method
- Removedextract_variable
- Removedfind_annotation_usages
- Removedfind_casts
- Removedfind_catch_blocks
- Removedfind_circular_dependencies
- Removedfind_field_writes
- Removedfind_implementations
- Removedfind_instanceof_checks
- Removedfind_large_classes
- Removedfind_method_references
- Removedfind_naming_violations
- Removedfind_possible_bugs
- Removedfind_references
- Removedfind_reflection_usage
- Removedfind_tests
- Removedfind_throws_declarations
- Removedfind_type_arguments
- Removedfind_type_instantiations
- Removedfind_unused_code
- Removedget_call_hierarchy_incoming
- Removedget_call_hierarchy_outgoing
- Removedget_classpath_info
- Removedget_complexity_metrics
- Removedget_dependency_graph
- Removedget_di_registrations
- Removedget_diagnostics
- Removedget_document_symbols
- Removedget_enclosing_element
- Removedget_field_at_position
- Removedget_hover_info
- Removedget_javadoc
- Removedget_method_at_position
- Removedget_project_structure
- Removedget_quick_fixes
- Removedget_signature_help
- Removedget_super_method
- Removedget_symbol_info
- Removedget_type_at_position
- Removedget_type_hierarchy
- Removedget_type_members
- Removedget_type_usage_summary
- Removedgo_to_definition
- Removedhealth_check
- Removedinline_method
- Removedinline_variable
- Removedload_project
- Removedorganize_imports
- Removedrename_symbol
- Removedsearch_symbols
- Removedsuggest_imports
- Removedvalidate_syntax
63 tool updatesv1.2.0Apr 15, 2026
- First observedanalyze_change_impact
- First observedanalyze_control_flow
- First observedanalyze_data_flow
- First observedanalyze_file
- First observedanalyze_method
- First observedanalyze_type
- First observedapply_quick_fix
- First observedchange_method_signature
- First observedconvert_anonymous_to_lambda
- First observedextract_constant
- First observedextract_interface
- First observedextract_method
- First observedextract_variable
- First observedfind_annotation_usages
- First observedfind_casts
- First observedfind_catch_blocks
- First observedfind_circular_dependencies
- First observedfind_field_writes
- First observedfind_implementations
- First observedfind_instanceof_checks
- First observedfind_large_classes
- First observedfind_method_references
- First observedfind_naming_violations
- First observedfind_possible_bugs
- First observedfind_references
- First observedfind_reflection_usage
- First observedfind_tests
- First observedfind_throws_declarations
- First observedfind_type_arguments
- First observedfind_type_instantiations
- First observedfind_unused_code
- First observedget_call_hierarchy_incoming
- First observedget_call_hierarchy_outgoing
- First observedget_classpath_info
- First observedget_complexity_metrics
- First observedget_dependency_graph
- First observedget_di_registrations
- First observedget_diagnostics
- First observedget_document_symbols
- First observedget_enclosing_element
- First observedget_field_at_position
- First observedget_hover_info
- First observedget_javadoc
- First observedget_method_at_position
- First observedget_project_structure
- First observedget_quick_fixes
- First observedget_signature_help
- First observedget_super_method
- First observedget_symbol_info
- First observedget_type_at_position
- First observedget_type_hierarchy
- First observedget_type_members
- First observedget_type_usage_summary
- First observedgo_to_definition
- First observedhealth_check
- First observedinline_method
- First observedinline_variable
- First observedload_project
- First observedorganize_imports
- First observedrename_symbol
- First observedsearch_symbols
- First observedsuggest_imports
- First observedvalidate_syntax

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-09-09 19:46 across 75 tools

Disambiguation3/5

While many tools have distinct purposes, there are several overlapping ones: e.g., get_type_at_position, get_symbol_info, and get_hover_info all return type/symbol info; analyze_file vs get_document_symbols+get_diagnostics overlaps; get_type_usage_summary vs find_type_instantiations/find_casts etc. Also, find_unused_code and find_unreachable_code are conceptually similar. The detailed descriptions help but an agent might struggle to pick the right one.

Naming Consistency3/5

Tool names mostly follow a verb_noun pattern (load_project, search_symbols, get_*, find_*, analyze_*, extract_*). However, there is inconsistency: some use 'get_' (get_type_at_position) and others use 'analyze_' (analyze_type) for similar operations; also 'find_*' is used for both searching usages (find_references) and finding issues (find_possible_bugs). Mixing verbs like 'get', 'find', 'analyze', 'extract', 'inline', 'change', 'apply' is natural but the distinction is not always clear.

Tool Count2/5

75 tools is excessive for a typical MCP server. Many tools are micro-optimizations or fine-grained variants (e.g., multiple get_*_at_position tools, and many find_* for each usage type). This makes the tool set overwhelming and increases selection complexity. It would be more appropriate to have 10-20 well-defined tools covering the same functionality.

Completeness4/5

The tool set covers a broad range of Java analysis and refactoring operations: navigation, references, hierarchy, diagnostics, refactoring (rename, extract, inline, pull up/push down), and code quality analysis (complexity, dependency, circular deps). It is quite complete for a language server, with minor gaps like lacking a tool for global code search (only search_symbols) or a way to list all files.

Maintenance

ActivityInactive

ResponsivenessWithin a week

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

neverinfamous-memory-journal-mcp
ai.smithery
A MCP server built for developers enabling Git based project management with project and personal…
Version Control Developer Tools Project Management
320
JFrog Remote MCP Server
io.github.jfrog
MCP Server for JFrog, providing tools for development and artifact management.
Developer Tools CI/CD & DevOps Cloud Platforms
215
developer
io.github.doc2mcp
MCP server for developer documentation, generated by doc2mcp.
Documentation Access Developer Tools
24
looptool
dev.looptool
An MCP server that automatically collects feedback on your MCP server.
Monitoring Developer Tools
2

Related MCP Servers

code-graph-mcp
Developer Tools Code Analysis Software Architecture
eas4ai
A
license
A
quality
D
maintenance
MCP server for comprehensive code analysis, navigation, and quality assessment across 25+ programming languages.
Updated a year ago (2025-07-26 13:27 UTC)
9
88
MIT
java-jdtls-mcp-server
Developer Tools Code Analysis
SachieWang
A
license
A
quality
B
maintenance
A high-performance MCP server that bridges AI agents with Java codebases, providing professional-grade Java language intelligence via Eclipse JDT.LS.
Updated 6 months ago (2026-03-15 08:28 UTC)
15
13 npm
2
GPL 3.0
docsgrep
Code Analysis Documentation Access Developer Tools
reasvyn
A
license
B
quality
B
maintenance
A high-performance MCP server for intelligent documentation search, proactive bug detection, and semantic analysis of codebases.
Updated 2 months ago (2026-07-11 11:52 UTC)
25
15 npm
MIT
codex-java-lsp
Developer Tools Code Analysis
lkyprogramer
A
license
B
quality
B
maintenance
A Codex MCP server that provides low-token Java semantic navigation using source indexing and optionally JDT Language Server for enhanced symbol, references, and diagnostics.
Updated 2 days ago (2026-09-12 01:27 UTC)
7
1
Apache 2.0

JavaLens: AI-First Code Analysis for Java

Built for AI Agents

Compiler-Accurate Analysis

AI Training Bias Warning

What is JavaLens?

Why Not LSP?

Installation

Prerequisites

Install from GitHub Releases (recommended — Java only)

Install via npm (requires Node.js 18+)

Configure MCP Client

Auto-Load a Project

How Workspaces Work

Workspaces Are Outside Your Source

Session Lifecycle

Tools

Navigation (10 tools)

Fine-Grained Reference Search (9 tools)

Analysis (20 tools)

Compound Analysis (4 tools)

Refactoring (16 tools)

Quick Fixes (5 tools)

Metrics (5 tools)

Project & Infrastructure (6 tools)

Usage

Basic Workflow

Coordinate System

Path Handling

Important Notes

Disk Synchronization

Refactoring Returns Edits

Session Isolation

Build System Support

Configuration

Building from Source

Build Requirements

Testing

Architecture

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers