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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that nothing is cut ("every reference at every depth is listed and counted"), explains the potentialMatches caveat for unconfirmed JDT matches and that they are never counted as results, defines the transitive node types followed (calls, instantiations, field accesses, override declarations), and notes INVALID_PARAMETER for out-of-range depth. This is rich behavioral context beyond any structured field.

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

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

Front-loaded with the purpose and organized under USAGE, OUTPUT, and Options headings, so it is easy to scan. It is longer than average, and the potentialMatches paragraph contains some convoluted phrasing ("as many as the results it stands beside may list"), but nearly every sentence earns its place for a 6-parameter tool with no output schema.

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

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

For a tool with no output schema and no annotations, the description adequately explains return shapes (callSites vs affectedMethods/affectedFiles), the potentialMatches structure, mode behavior, and the load_project prerequisite. It omits exact output field shapes and any performance/large-project caveats, leaving minor gaps.

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

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

Schema coverage is already 100%, but the description goes well past the schema: it enumerates the meaning of depth=1, 2, and 3, states that any other value is invalid, clarifies that maxResults applies only to affectedMethods in transitive mode, and specifies that transitive returns affectedMethods + affectedFiles instead of callSites. This adds substantial semantics over the raw parameter definitions.

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

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

States a specific verb+resource ("Analyze the blast radius of changing a symbol") and defines the scope as all files/call sites affected, grouped by file. This distinguishes it from narrow siblings like find_references or get_call_hierarchy_incoming, though it never names a sibling to route between them. Clear and non-tautological.

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

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

Provides an explicit invocation example and a prerequisite ("Requires load_project to be called first"), plus mode-selection guidance distinguishing depth=1/2/3 semantics and when to use transitive closure. It does not explicitly say when to prefer this over find_references or get_call_hierarchy_incoming, so it stops short of full when/when-not/alternatives routing.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the whole burden and discharges it richly: truncation semantics (meta.truncated, totalCount vs returnedCount), INVALID_PARAMETER behavior for negative limits, position-resolution rules (declaration file/line, class-file methods reporting no callees), and what potentialMatches/unresolvedSupertypes mean. This is far beyond what the schema reveals.

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

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

The opening is well front-loaded (USAGE, OUTPUT, Combines), but the body sprawls across many dense paragraphs, and the potentialMatches explanation and the load_project prerequisite are stranded toward the very end rather than grouped with related material. Much of the length is justified by the absent output schema, but it is not tight.

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

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

For a high-complexity tool with no output schema, the description documents the returned structure (counts, meta fields, potentialMatches, unresolvedSupertypes), edge cases, and the sequencing prerequisite. An agent has enough to invoke it correctly and interpret the result without a schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the interaction between callers.count/callees.count and the maxCallers/maxCallees truncation limits, and flags that negative values are INVALID_PARAMETER. The zero-based note merely echoes the schema.

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

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

The description opens with a specific verb+resource ("Comprehensive method analysis") and explicitly enumerates what it covers: signature, parameters, exceptions, callers, callees, overrides. It also distinguishes itself from siblings by naming get_method_at_position and the call-hierarchy tools it replaces, so an agent can route without opening any schema.

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

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

It gives an explicit when-to-use rule ("Use this instead of multiple calls to get_method_at_position + call hierarchy tools") and a hard prerequisite ("Requires load_project to be called first"). It does not state when to prefer the narrower single-purpose siblings instead, so it falls short of a full when/when-not/alternatives treatment.

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

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

With no annotations, the description carries the full burden and delivers: it documents the output shape, discloses that hierarchy.unresolvedSupertypes and potentialMatches are conditionally present, explains what potentialMatches counts and why, and states maxUsages below 0 is INVALID_PARAMETER. These are real behavioral traits 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.

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

Front-loaded with purpose, usage, and output, and each section is labeled. The middle paragraphs on unresolvedSupertypes and potentialMatches are dense and slightly tangled, but since there is no output schema they largely earn their place. Minor tightening would help.

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

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

No output schema exists, so the description must explain return values, and it does in detail, including conditional fields and the unresolved/uncertain match semantics. It also supplies the prerequisite and parameter error condition, leaving nothing essential for a correct call missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a validation rule absent from the schema ('maxUsages below 0 is INVALID_PARAMETER') and clarifies the semantics of the potentialMatches/maxUsages listing, giving it an edge over the schema alone.

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

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

States a specific verb+resource ('Comprehensive type analysis') and enumerates exactly what it aggregates: type info, members, hierarchy, usage summary, and diagnostics. It explicitly names the siblings it replaces (get_type_members, get_type_hierarchy, get_type_usage_summary), so an agent can distinguish it from those without opening any schema.

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

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

Explicitly routes the agent away from three sibling tools and states the prerequisite 'Requires load_project to be called first.' It gives a concrete usage example. It stops short of a 'when-not' condition (e.g. when a single-purpose tool is preferable), so it is strong but not fully exhaustive.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full burden and does so exhaustively: it discloses what gets rewritten (calls, Javadoc links, lambda parameters, implicit super() calls, static imports), how refusals surface (INVALID_PARAMETER with JDT messages), that compile errors do not refuse but appear in introducedProblems/warnings, that potentialMatches holds unconfirmed places, edit ordering, and ZERO-BASED coordinates. This is far richer than typical 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.

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

Purpose, USAGE, and OUTPUT are correctly front-loaded, which helps orientation. However the body is extraordinarily long with dense, sometimes convoluted prose (e.g., the multi-clause override/inheritance sentence), and the sheer size makes it harder to scan than a complex refactoring tool strictly requires.

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

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

There is no output schema, yet the description fully explains the return shape (text edits with replace/insert types, isDeclaration, oldText/newText, line/column/offset, per-file ordering) and the auxiliary result fields. For a 6-parameter mutation tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% (baseline 3), but the dedicated 'PARAMETER OPERATIONS' section adds real meaning beyond the schema: how to add a parameter with a defaultValue, remove one, rename via oldName (including how references and @param tags follow), and reorder, plus the INVALID_PARAMETER conditions. That exceeds what the schema's field descriptions convey.

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

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

Opens with a specific verb+resource+scope: 'Change method signature (parameters, return type, or name) and update all call sites.' It distinguishes itself from the sibling rename_symbol (which it explicitly routes annotation-type elements to), so an agent can tell them apart without opening either schema.

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

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

The 'USAGE: Position on method declaration, provide changes' line plus the prerequisite 'Requires load_project to be called first' give clear invocation context, and it names rename_symbol as the alternative for annotation-type elements. It stops short of a full when/when-not contrast against refactoring siblings like extract_method or inline_method.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden and does well: it discloses that edits are returned as text and must be applied by the caller ('apply them yourself'), that warnings come from JDT's condition checking, and that coordinates are zero-based. It lacks permission/scope or reversibility notes, so not a 5.

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

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

The labeled sections (USAGE, OUTPUT, IMPORTANT) front-load the purpose and make scanning easy with zero filler sentences. The OUTPUT paragraph is dense but earns its place by describing a structure with no output schema.

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

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

For a mutation/refactoring tool with no annotations and no output schema, the description covers the critical gaps: output shape (editsByFile, text edits, warnings), the prerequisite (load_project), and the coordinate convention. It could say more about cross-file side effects, but the essentials are present.

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

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

Schema coverage is 100%, so the schema already documents all five parameters including getterName/setterName defaults. The description only restates 'position on the field name' and 'optionally name the accessors,' adding no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ('Encapsulate a field') and immediately defines the mechanics: 'generate a getter/setter pair and rewrite all direct accesses (in this and other files) to go through them.' This clearly distinguishes it from siblings like rename_symbol, extract_method, or inline_method.

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

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

'USAGE: Position on the field name; optionally name the accessors' tells the agent how to invoke it, and 'Requires load_project to be called first' gives a concrete prerequisite. It does not name a when-not condition or an explicit alternative refactoring, so it falls short of a 5.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that a new interface file is produced and that the original class is edited with an 'implements' clause, plus import-handling rules and zero-based coordinates. It is slightly ambiguous about whether the class edit is applied automatically or merely returned.

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

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

Purpose is front-loaded, then cleanly segmented with USAGE, OUTPUT, and IMPORTANT markers. The import-handling sentence is somewhat dense but earns its place by describing real behavior.

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

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

For a refactoring tool with no annotations and no output schema, the description covers output shape ('Interface file content and class modification edit'), prerequisite, and coordinate convention. Only the apply-vs-return ambiguity for the class edit keeps it from being fully complete.

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

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

Schema coverage is 100%, so the schema already documents all five parameters including the default for methodNames. The description reinforces positioning and the default but adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Extract an interface from a class containing selected public methods') and distinguishes itself from refactoring siblings like extract_method and extract_superclass. An agent can tell exactly what artifact is produced without opening the schema.

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

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

The USAGE line gives concrete positioning ('Position on class, provide interface name, optionally specify methods') and the prerequisite 'Requires load_project to be called first' is spelled out. It does not name an explicit alternative refactoring to choose over this one, so it stops short of a 5.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full behavioral disclosure: it explains that nothing is written and the caller must create the file and apply edits, details the output fields (createdFiles, editsByFile, warnings), and gives formatting rules for warnings. This is exactly the kind of side-effect and result-shape information an agent needs beyond structured fields.

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

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

The description is front-loaded with its core purpose and uses clear USAGE/OUTPUT/IMPORTANT sections. However, the warnings-ordering sentence is dense and awkwardly phrased ('by the place each names... those naming one place in JDT's order, those naming none last'), which slightly reduces readability.

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

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

Given the absence of annotations and an output schema, the description is complete enough: it covers prerequisites, invocation, coordinate system, output structure, and side effects. An agent has everything needed to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters, including zero-based coordinates. The description adds only minor emphasis ('Position on the member to extract', 'provide the new superclass name') and repeats the zero-based warning already present in the schema, so it does not add much semantic value beyond the schema.

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

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

The description states a precise verb and resource: 'Extract a new superclass from a class', and describes the transformation (member moves up, class extends new superclass). This clearly differentiates it from sibling refactorings like extract_method, pull_up, and extract_interface.

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

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

It gives concrete invocation guidance: 'Position on the member to extract; provide the new superclass name', and states a prerequisite ('Requires load_project to be called first'). It does not, however, say when to prefer this tool over 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.

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

With no annotations, the description carries the full burden and does well: it discloses that the tool returns text edits rather than applying them ('The caller should apply these edits'), names a specific failure mode with its error code (void expression or null literal -> INVALID_PARAMETER), and flags the zero-based coordinate contract. It stops short of describing edge cases like overlapping/invalid selections or multi-edit ordering, so it is not fully exhaustive.

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

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

The block is front-loaded with the core purpose and uses labeled sections (USAGE, OUTPUT, IMPORTANT) that scan quickly. There is mild redundancy between 'Returns the text edits needed to extract the expression' and 'OUTPUT: Variable declaration and replacement edits', which keeps it from a 5.

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

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

For a 6-parameter mutation-style refactoring tool with no annotations and no output schema, the description covers the essentials: output shape, caller responsibility, error behavior, coordinate system, and the load_project prerequisite. The main omission is any statement of sibling alternatives, which is a routing gap rather than an invocation gap.

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

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

Schema description coverage is 100%, so every parameter including the optional variableName is already documented in the schema. The description's zero-based coordinate warning and 'select expression by start/end positions' merely restate what the schema fields already say, adding no new parameter-level meaning beyond the baseline.

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

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

The first sentence gives a specific verb (Extract) and resource (an expression at a given position into a local variable), which is concrete and actionable. However, it never distinguishes itself from the closely related siblings extract_method and extract_constant, so the agent must infer the boundary from the name alone.

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

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

The 'USAGE' line tells the agent how to invoke it (select by start/end positions) and the description states the prerequisite 'Requires load_project to be called first', which is useful. But there is no guidance on when to prefer this over extract_method or extract_constant, so usage is only implied.

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

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the behavioral disclosure burden. It explains output semantics well, including the special `potentialMatches` field, its relation to unresolved types, and that those matches are never counted as real results. It could add more on permissions or result format, but the unusual search behavior is covered.

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

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

The description is front-loaded with purpose and usage, then examples, then edge-case output behavior, and finally the prerequisite. The `potentialMatches` paragraph is somewhat wordy but earns its place because no output schema exists to explain that field.

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

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

Given no annotations, no output schema, and a simple search operation, the description is nearly complete. It covers the input requirement, output locations, the special `potentialMatches` semantics, and the `load_project` prerequisite. It omits only minor return-detail or pagination specifics already implied by `maxResults`.

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

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

Schema description coverage is 100%, so the schema already documents both `typeName` and `maxResults`. The description reinforces that `typeName` must be fully qualified and gives multiple examples, but this largely duplicates the schema's own example and does not add syntax or format details beyond it.

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

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

The description states a specific verb and resource: finding all usages of an annotation type in the project. It also explicitly notes a differentiator, JDT-UNIQUE, indicating why this search is distinct from LSP-based sibling tools. An agent can identify the tool's purpose without opening the schema.

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

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

It gives clear usage context: provide a fully qualified annotation name as `typeName`, and load_project must be called first. It does not explicitly say when not to use this tool or name an alternative sibling like find_references, but the annotation-specific scope is clear.

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

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

With no annotations provided, the description carries the full burden and does so well: it documents the OUTPUT shape, the tricky potentialMatches semantics (possible-but-unconfirmed matches, never counted as results), and the load_project prerequisite. It does not explicitly state read-only/safety behavior, but 'find' plus the read-only nature is strongly implied.

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

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

Front-loaded with the one-line purpose, then clearly sectioned USAGE/OUTPUT/Useful-for blocks. The potentialMatches paragraph is dense but earns its place by clarifying an otherwise confusing output edge case. Minor redundancy with the schema keeps it from a 5.

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

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

With no output schema, the description correctly supplies return-value semantics, including the potentialMatches structure and its count/locations fields, and states the load_project prerequisite. An agent has everything needed to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so both typeName and maxResults are already documented in the schema. The description's 'Provide fully qualified type name' only restates the schema's typeName description and says nothing about maxResults, so it adds no meaning beyond the structured fields. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Find all casts to a type') and even supplies the syntactic form ((Foo) x). It positions itself against the broader toolset by noting the search is fine-grained and unavailable in LSP, so an agent can distinguish it from siblings like find_references or find_instanceof_checks.

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

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

Gives clear when-to-use context via the 'Useful for' list (unsafe downcasts, refactoring, conversion patterns) and a hard prerequisite ('Requires load_project to be called first'). It stops short of naming alternative sibling tools or stating when not to use it, so it is context-rich but not fully routing.

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

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

With no annotations, the description carries the full burden and largely succeeds: it discloses the JDT-unique nature, the output shape, the load_project precondition, and a nuanced explanation of potentialMatches (unconfirmed matches, counted/listed separately). It does not cover result truncation behavior or performance limits, so a small gap remains.

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

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

Core purpose is front-loaded, and labeled sections (USAGE, OUTPUT, Useful for) make it scannable. The 'Useful for' bullets are somewhat redundant with the opening sentence, and the potentialMatches paragraph is dense, but nothing is off-topic.

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

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

With no output schema and no annotations, the description compensates by explaining the return content and the special potentialMatches field, plus the load_project prerequisite. It is largely complete for a read-only search tool, missing only edge details like result capping behavior.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents typeName and maxResults with examples and defaults. The description's 'USAGE' line re-states the typeName format but adds no syntax or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Find all catch blocks for an exception type') and clarifies scope with the '(catch(ExceptionType e))' signature form. It is unmistakable what the tool does, though it never names a sibling (e.g. find_throws_declarations) to distinguish itself.

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

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

It gives a prerequisite ('Requires load_project to be called first') and a concrete usage instruction ('Provide fully qualified exception type name as typeName'), plus a list of intended scenarios. It stops short of explicit when-not-to-use or alternative-tool routing, so it misses the top tier.

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

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

With no annotations, the description carries the burden and does well: it discloses the algorithm (Tarjan's SCC), what the output contains (cycle paths and affected packages), and the specific failure mode for maxCycleLength < 2 (INVALID_PARAMETER). It omits scale/performance characteristics and behavior when the project has no cycles.

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

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

Front-loaded with the verb+resource, then labeled USAGE/OUTPUT blocks and a prerequisite line — easy to scan. Minor redundancy between "Detect cycles" and "circular dependency cycles," but nothing wasted.

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

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

No output schema exists, and the description compensates by describing the return value (list of cycles with paths and affected packages). Combined with the prerequisite and validation rule, an agent has what it needs; only edge-case behavior (empty results, project size limits) is unspecified.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema: what maxCycleLength actually bounds ("the most packages a reported cycle joins") and a usage example showing packageFilter as a prefix. This goes past restating field descriptions.

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

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

States a specific verb and resource: detect cycles / circular dependency cycles in packages. The purpose is unambiguous and clearly distinct from graph-oriented siblings like get_dependency_graph or find_unused_code, though it never names those alternatives explicitly.

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

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

Provides two concrete invocation patterns (bare and with packageFilter) and a hard prerequisite: "Requires load_project to be called first." It does not state when to prefer this over e.g. get_dependency_graph, so no 5.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it documents the zero-based coordinate convention, the INVALID_PARAMETER failure mode for out-of-range maxResults, and the unconfirmed-match semantics. It stops short of describing result ordering or whether the declaration site is included, which keeps it from a 5.

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

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

Well-structured with USAGE/OUTPUT/IMPORTANT labels and the core purpose front-loaded. The potentialMatches paragraph is dense and worth its length since no output schema exists, though the definition is on the longer side.

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

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

No output schema exists and no annotations are present, yet the description covers the return shape ('List of locations'), the conditional potentialMatches field with its count/locations substructure, prerequisites, and error semantics. It is complete for a position-based search tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it re-emphasizes zero-based coordinates, states the maxResults valid range and the exact error for violations, and describes the potentialMatches structure that the schema does not cover.

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

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

Opens with a specific verb+resource ('Find all write accesses (mutations) to a field') and explicitly contrasts itself with the sibling find_references ('this returns only locations where the field value is changed'). An agent can distinguish it from the reference-finding tools without opening a schema.

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

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

Gives an explicit precondition ('Position cursor on a field declaration or reference'), a dependency ('Requires load_project to be called first'), an alternative and the condition selecting it ('Unlike find_references which returns all usages'), and motivation ('useful for data flow analysis'). Nothing needed for correct invocation is left to inference.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains zero-based coordinates, maxResults validation ('outside 0 to 1000 is INVALID_PARAMETER'), the prerequisite load_project, and detailed semantics of potentialMatches including when it is present and why matches may be unconfirmed.

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

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

The description is front-loaded with purpose, usage, and output, which is good. However, the explanation of potentialMatches is repetitive: it appears once as 'potentialMatches are the places...' and again in a longer paragraph, without enough added clarity to justify the duplication.

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

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

For a 4-parameter tool with no output schema and no annotations, the description supplies everything needed: purpose, usage, output summary, coordinate convention, parameter constraints, prerequisite, and the special potentialMatches behavior. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying that maxResults outside 0 to 1000 is an INVALID_PARAMETER error and by reinforcing the zero-based coordinate convention for line and column.

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

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

The description states a specific verb and resource: 'Find implementations of an interface or extensions of a class.' This is distinct from sibling tools like find_references or get_type_hierarchy, and the agent can identify the operation directly from the first sentence.

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

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

The description provides clear invocation context with 'USAGE: Position on a type (interface or class), find all implementors/subclasses' and a prerequisite: 'Requires load_project to be called first.' It does not explicitly name alternatives or when-not conditions, but the context is sufficient for correct use.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the OUTPUT shape, the load_project prerequisite, and a detailed semantics note that potentialMatches are unresolved/unconfirmed matches never counted or listed as results. It omits any statement about truncation behavior relative to maxResults, keeping it just under 5.

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

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

The core purpose, uniqueness note, usage, and output are front-loaded before the longer potentialMatches explanation. The potentialMatches paragraph is verbose for the value it adds, but every part is relevant and no sentence is filler.

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

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

There is no output schema, so the description correctly supplies the return semantics: where instanceof occurrences are reported and how the anomalous potentialMatches collection is structured and counted. Combined with the prerequisite and input format, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both typeName and maxResults are already documented in the schema. The description only restates 'fully qualified type name' for typeName and says nothing new about maxResults, so the baseline 3 applies.

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

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

States a precise verb+resource ('Find all instanceof checks for a type') and even disambiguates the syntax being matched with the example '(x instanceof Foo)'. The 'JDT-UNIQUE: not available in LSP' note plus the narrow construct focus clearly separates it from siblings like find_casts, find_type_instantiations, and find_references.

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

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

Gives a concrete prerequisite ('Requires load_project to be called first') and an input instruction ('Provide fully qualified type name'), plus a useful-for list that implies when the tool applies. It does not explicitly name alternative tools (e.g., find_casts vs find_instanceof_checks) or state when NOT to use it, so it falls short of a 5.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden and does so well: it discloses the zero-based coordinate system, the load_project prerequisite, and detailed semantics of the potentialMatches field (count is exact, locations listed, never counted as results). Output format and prerequisite are covered; return pagination/interaction with maxResults is left implicit.

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

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

Front-loads the purpose and the JDT-UNIQUE differentiator, which is the highest-value information. The potentialMatches paragraph is long and the 'Useful for' bullet list largely restates an already-clear purpose, adding mild bloat, but the important content is well ordered.

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

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

Despite having no output schema and no annotations, the description covers what the tool returns (all reference locations plus potentialMatches), the entry coordinate convention, and the required prior step. An agent has everything needed to call and interpret this correctly.

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

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

Schema description coverage is 100%, so line, column, filePath and maxResults are already documented with zero-based notes. The description restates the zero-based constraint and the position-or-details pattern but adds no syntax beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and a precisely-scoped resource ('method reference expressions (Foo::bar lambda syntax)'), which distinguishes it from the sibling find_references. The explicit JDT-UNIQUE note further tells the agent this fine-grained search is not available elsewhere, removing ambiguity about which tool to pick.

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

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

Gives concrete invocation context ('Position on a method, or provide method details') and a hard prerequisite ('Requires load_project to be called first'). It does not, however, name an explicit alternative tool or state when-not-to-use it versus find_references, so it stops just short of the top band.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden and largely delivers: it discloses error semantics (INVALID_PARAMETER for bad severity, FILE_NOT_FOUND for an unknown file), the default scope (all files), and the sequencing requirement (load_project first). It is silent on result granularity and runtime cost, which are secondary for a read-only analysis tool.

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

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

Front-loaded with purpose, then detection categories, then parameter and error details in clearly delimited sections. The two near-duplicate USAGE lines and the OUTPUT line add slight padding, but nothing is misleading or wasted at length.

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

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

For a two-param, no-output-schema, no-annotation tool, the description covers purpose, scope, prerequisites, and error paths. The main gap is that the shape of the returned issue list (file, line, message fields) is not characterized, which an agent would want before rendering results.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: severity is compared case-insensitively, 'all' is the default, and any unrecognized value is rejected with INVALID_PARAMETER. The filePath semantics (default all files, must name a project source file) are also spelled out.

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

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

States a specific verb+resource ('Find possible bugs and code quality issues') and enumerates exactly which bug classes it detects (null pointer risks, resource leaks, empty catch blocks, comparison issues, synchronization issues). This clearly separates it from siblings like validate_syntax, find_unused_code, and find_unreachable_code, which cover different concerns.

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

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

Provides two concrete invocation examples (whole-project vs single file) and a hard prerequisite ('Requires load_project to be called first'). It does not explicitly name alternative tools for overlapping concerns such as syntax validation or unused-code detection, so it stops short of full when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the SYMBOL_NOT_FOUND error for unresolvable names, the INVALID_PARAMETER condition for maxResults, the zero-based coordinate convention, and the subtle semantics of potentialMatches (unconfirmed matches never counted as results). The load_project prerequisite is also stated, which is essential operational context.

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

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

Front-loaded purpose then USAGE/OUTPUT headers make it scannable, and the prerequisite sits at the end where it is easy to catch. The potentialMatches paragraph is dense and somewhat long, but each clause explains a genuinely non-obvious return behavior, so the length is largely earned.

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

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

There is no output schema, so the description must explain returns, and it does: 'List of reference locations with context' plus the detailed potentialMatches breakdown. Combined with error conditions and the load_project prerequisite, an agent has enough to call and interpret this tool correctly; only alternative-tool routing is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it reinforces the zero-based convention as an 'IMPORTANT' caveat and restates the maxResults validity window (0-1000) as an error condition rather than just a default.

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

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

States a specific verb+resource: 'Find all references to a symbol across the project.' An agent understands this is a usage-search tool. However, it does not distinguish itself from near-siblings like find_method_references or find_annotation_usages, so the boundary is inferred from the name rather than stated.

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

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

'USAGE: Position on symbol, find all usages' implies you must first have a cursor position, and the closing line states the load_project prerequisite. There is no when-not guidance and no routing to alternative reference-search 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.

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses output grouping, truncation behavior (meta.truncated, meta.totalCount), how maxResults applies per method across overloads, and the special potentialMatches semantics (unresolved types never counted or listed as results). This is rich behavioral disclosure beyond what any structured field provides.

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

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

Front-loaded with purpose and organized into USAGE/OUTPUT/Detects sections, but the potentialMatches explanation is verbose and partly redundant ('count is their exact number, and locations lists them, as many as the results it stands beside may list'). The load_project prerequisite is buried at the very end rather than surfaced up front.

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

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

With no output schema, the description must explain return values and does: it covers summary counts, totalCalls, meta truncation flags, and the potentialMatches edge case. For a single-optional-param analysis tool, nothing an agent needs to interpret or call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: maxResults caps results 'for each reflection method, all its overloads together' in source order (by file, then position) – a per-method-across-overloads and ordering rule not present in the schema's terse 'Maximum results per reflection method'.

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

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

States a specific verb and resource ('Find places where Java reflection API is used') and enumerates exactly which calls count (Class.forName, getDeclaredMethod, Method.invoke, etc.). It also distinguishes itself from sibling reference-search tools by noting these usages are 'invisible to static reference searches', so an agent can tell it apart from find_references without opening a schema.

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

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

Gives a hard prerequisite ('Requires load_project to be called first') and an implicit when-to-use rationale (reflection calls that evade static reference searches). It does not name a specific sibling alternative or state exclusions, so it is clear context rather than explicit routing.

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

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.

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.

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.

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.

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.

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.

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

No annotations are supplied, so the description carries the full burden and does notable work: it discloses the load_project prerequisite and explains the non-obvious potentialMatches field (unconfirmed matches never counted or listed as results). It still does not state read-only status or rate/size limits explicitly, so it is strong but not exhaustive.

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

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

Purpose is front-loaded in the first line, followed by differentiator, usage, output, and use cases in a scannable structure. The potentialMatches paragraph is dense and slightly long but each clause carries real semantic weight about result semantics.

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

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

With no output schema and no annotations, the description compensates by describing the output ('all methods that declare throws ExceptionType') and the subtle potentialMatches sub-structure, plus the prerequisite. An agent has everything it needs to invoke and interpret the result.

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

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

Schema coverage is 100%, so both parameters are already documented (typeName as fully qualified name, maxResults default 100). The description restates the typeName convention but adds no format or syntax detail beyond what the schema provides, matching the baseline for high coverage.

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

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

States a precise verb and resource ('Find all throws declarations of an exception type in method signatures') and immediately scopes what counts ('All methods that declare throws ExceptionType'). It is distinguishable from siblings like find_catch_blocks or find_references without opening the schema.

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

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

Provides a 'Useful for' list of concrete scenarios and the hard prerequisite 'Requires load_project to be called first', plus the JDT-vs-LSP differentiation. It stops short of naming sibling tools that might be mistaken for it, so no explicit when-not guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses the important load_project prerequisite and explains the potentialMatches field's semantics, including that unresolved types are never counted as results. It omits nothing critical for a read-only search, though it doesn't address result limits or error behavior beyond the schema's maxResults.

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

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

The description is front-loaded with purpose, then blocks for JDT-UNIQUE, USAGE, OUTPUT, and the potentialMatches detail. Each section serves a purpose, though the 'Useful for' bullets lightly echo the opening sentence and the potentialMatches paragraph is dense, keeping it just short of maximally tight.

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

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

With no output schema, the description must describe return values and it does: locations of generic-argument usages plus the nuanced potentialMatches structure. Combined with the load_project prerequisite and the LSP distinction, an agent has everything needed to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so typeName and maxResults are already documented structurally. The description's 'Provide fully qualified type name' reinforces the typeName constraint but adds little beyond the schema, and maxResults is untouched. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource with concrete syntax examples (List<Foo>, Map<K, Foo>), and explicitly positions itself against alternatives by noting it is not available in LSP and that it searches only generic-argument positions. An agent can distinguish it from find_references, find_type_instantiations, and find_casts without opening any schema.

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

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

Clear context is given via the 'USAGE' line and 'Useful for' scenarios, plus the JDT-UNIQUE note implying it covers ground other searches do not. However, it never names sibling tools as alternatives nor states explicit exclusions (e.g., 'use find_references for non-generic usages'), so the when-not guidance is only implied.

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

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

With no annotations, the description carries the full burden, and it does meaningful work: it explains that potentialMatches holds unconfirmed/unresolved candidates that are never counted as results, and it discloses the load_project prerequisite. It does not state read-only safety or pagination behavior, leaving that gap.

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

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

Purpose is front-loaded and the labeled sections (USAGE, OUTPUT, Useful for) scan quickly. The potentialMatches paragraph is dense and awkwardly worded ('as many as the results it stands beside may list'), which costs it a point.

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

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

There is no output schema, so the description must explain return semantics, and it does: locations of `new` sites plus the potentialMatches structure and counting rules. The main omission is that the return shape is described in prose rather than a schema, and maxResults behavior is never addressed.

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

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

Schema description coverage is 100%, so both typeName and maxResults are already documented in the schema; baseline is 3. The description only reiterates the fully-qualified-name requirement and says nothing about maxResults or default behavior, adding marginal value beyond the schema.

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

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

The description gives a precise verb+resource (find all instantiations of a type, i.e. `new Foo()` calls) and even disambiguates from the LSP-equivalent tools by labeling itself 'JDT-UNIQUE'. An agent can distinguish it from siblings like find_instanceof_checks or find_method_references without opening any schema.

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

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

It states the calling convention explicitly ('USAGE: Provide fully qualified type name'), lists concrete scenarios (object creation patterns, factory candidates, coupling points), and gives the prerequisite ('Requires load_project to be called first'). It does not name alternative tools or state when NOT to use it, so it falls short of a full 5.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the burden and does well: it discloses the maxResults bound and the INVALID_PARAMETER failure mode, the load_project prerequisite, the output shape, and how potentialMatches ('never counted or listed as results') behaves. It doesn't state read-only/reversibility explicitly, but the query nature is evident.

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

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

Front-loads the core purpose and uses labeled USAGE/OUTPUT/IMPORTANT sections, which is easy to scan. It is somewhat long and mildly redundant ('all callers' restated as 'List of methods that call this method'), but nearly every sentence earns its place given the absent output schema.

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

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

For a 4-param query tool with no annotations and no output schema, the description covers output format, coordinate convention, bounds/error behavior, an edge case (potentialMatches) and a prerequisite. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% (baseline 3), and the description adds real value on top: it stresses ZERO-BASED coordinates and specifies that maxResults outside 0-500 is INVALID_PARAMETER. These constraints are behavioral semantics the schema alone doesn't fully convey.

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

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

States a specific verb+resource ('Find all callers of a method') and scopes it with '(incoming calls)', which cleanly distinguishes it from the sibling get_call_hierarchy_outgoing and other reference-style tools. An agent can identify the operation immediately.

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

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

Gives clear context for use ('understanding who depends on a method before changing it'), a positional prerequisite ('Position cursor on a method name'), and a hard dependency ('Requires load_project to be called first'). It does not name explicit alternatives such as find_references, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape, the load_project prerequisite, zero-based coordinates, and non-obvious edge-case semantics (lambda calls belong to the enclosing method, anonymous-class body calls do not, and class creation resolves to the superclass constructor). It omits error behavior when the cursor is not on a method, keeping it short of a 5.

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

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

Front-loaded with a one-line purpose followed by clearly labelled USAGE/OUTPUT/IMPORTANT blocks, which is easy to scan. The lambda/anonymous-class paragraph is dense and somewhat hard to parse, but it encodes genuine edge-case behavior that would otherwise be missing.

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

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

There is no output schema, so the description must explain returns and does so ('List of methods that this method calls'), plus it covers the load_project prerequisite and coordinate convention. It is nearly complete for a position-based query tool; only failure modes when no method is under the cursor are unaddressed.

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

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

Schema coverage is 100% and both 'line' and 'column' are already documented as zero-based, so the description's 'IMPORTANT: Uses ZERO-BASED coordinates' largely restates structured data. 'Position cursor on a method name' adds minor semantic value by indicating the coordinates must point at a method identifier, so baseline 3 applies.

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

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

States a specific verb and resource ('Find all methods called by a method') with the directional qualifier '(outgoing calls)' that cleanly separates it from the sibling get_call_hierarchy_incoming, which it names explicitly. An agent can tell the two apart without opening either schema.

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

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

'USAGE: Position cursor on a method name' tells the agent the required precondition and 'Requires load_project to be called first' gives the ordering dependency. It also states the analytical use case ('understanding what a method depends on'). It lacks an explicit when-not, but the incoming sibling reference covers the main alternative.

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

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full burden and does well: it describes the output structure, the default behavior of includeDetails, and how risk levels are derived. It does not explicitly state read-only behavior or error conditions, but otherwise gives strong 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.

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

The description is front-loaded with the core purpose and organized into usage, output, metrics, and risk sections. It is reasonably concise, though some metric and risk-level detail could be considered supplementary rather than essential.

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

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

There is no output schema and no annotations, so the description must explain return values and behavior. It does so effectively by describing line counts, summary/risk assessment, per-method details, and risk thresholds. Minor gaps remain around read-only guarantees and error behavior.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description repeats the includeDetails default and gives a filePath example, but does not add substantial meaning beyond what the schema already provides.

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

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

The description states a specific verb and resource: retrieve cyclomatic complexity, cognitive complexity, and LOC for a file. It is clearly distinguishable from most siblings by resource, though it does not explicitly differentiate itself from related analysis tools like analyze_file or analyze_method.

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

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

It provides a usage example and the prerequisite that load_project must be called first, which is useful context. However, it does not explain when to choose this tool over alternatives such as analyze_file, analyze_method, or health_check, so usage guidance is only implied.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains node naming, package-scope coverage, edge semantics, dependency types tracked, depth behavior, and error codes. It also discloses the load_project prerequisite.

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

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

The description is front-loaded with purpose and usage, then structured with output details and dependency types. It is somewhat long, but for a dependency-graph tool most of the detail is relevant and earns its place.

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

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

Given the absence of an output schema and annotations, the description explains the returned graph, node identity, package semantics, depth behavior, and failure modes. An agent has enough information to call the tool correctly.

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

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

Schema coverage is 100%, so parameter definitions are already strong, but the description adds meaningful semantics for scope, depth, node resolution, and package-scope behavior. It does not explicitly explain the includeExternal parameter, which keeps it from a 5.

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

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

The description states a specific verb and resource: "Get package/type dependencies." Examples for type and package scope make the operation unambiguous, but the description does not explicitly contrast itself with nearby tools such as get_type_hierarchy or find_circular_dependencies.

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

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

It gives concrete invocation examples for both scopes and notes that load_project must be called first. It also defines depth and error behavior, but does not say when to choose this tool over sibling dependency-related tools.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that unrecognized severity values are rejected with INVALID_PARAMETER, that filtering is case-insensitive, that all files are checked and counted even when maxResults truncates the list, and that meta.truncated signals truncation. It does not cover permissions or performance on very large projects, but the operational semantics are unusually well documented.

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

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

USAGE and OUTPUT are front-loaded before the finer filtering rules, so an agent gets the essential call shape immediately. The description is on the long side and the 'Useful for finding syntax errors, type mismatches, missing imports, etc.' sentence is largely filler, but the labeled structure keeps it scannable.

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

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

For a 3-parameter read tool with no annotations and no output schema, the description covers the invocation modes, the prerequisite, the meaning of each parameter, the shape of the return value (diagnostics with locations plus counts and a truncation flag), and the error path. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra credit by adding semantics the schema does not: case-insensitive severity matching with INVALID_PARAMETER rejection, and the non-obvious interaction where maxResults limits only the listed diagnostics while totalDiagnostics/errorCount/warningCount count everything.

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

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

The opening sentence gives a specific verb and resource ('Get compilation diagnostics (errors and warnings)') plus the scope (file or project). It is distinguishable from nearby siblings like validate_syntax or analyze_file because it names the artifact being returned (errors and warnings) rather than a generic analysis.

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

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

The USAGE line explicitly shows the two invocation modes: no-arg for all files and filePath for a single file, and it states the prerequisite 'Requires load_project to be called first.' It stops short of saying when to prefer this over siblings such as validate_syntax or find_possible_bugs, so it is clear context without alternatives.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that non-Spring projects return empty categories rather than erroring, explains the maxResults cap and its interaction with meta.totalCount/returnedCount/truncated, and carefully defines potentialMatches as unconfirmed, never-counted results. That is exactly the kind of behavioral context annotations would otherwise have to supply.

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

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

Front-loading is good (purpose, then USAGE/OUTPUT, then semantics), but the potentialMatches passage is verbose and grammatically tangled ('as many as the results it stands beside may list'), requiring re-reading. The meta/potentialMatches detail is repeated and could be tightened substantially.

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

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

No output schema and no annotations, yet the description fully specifies the return shape (categories, meta counters, potentialMatches), the prerequisite, and edge-case behavior. An agent has everything needed to invoke and interpret the result correctly.

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

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

Schema coverage is 100% and the single parameter's description ('Maximum results per annotation type (default 200)') is essentially duplicated in the prose. The description adds only marginal nuance about per-type truncation, which the schema text already conveys. Baseline 3 is correct.

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

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

States a specific verb and resource ('Find all dependency injection registrations') and then enumerates exactly what it scans for (Spring components, @Configuration, @Bean, @Autowired/@Inject). An agent can distinguish this from generic siblings like find_annotation_usages or get_dependency_graph without opening the schema.

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

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

Gives a clear prerequisite ('Requires load_project to be called first') and an explicit USAGE signature. However, it never names an alternative tool or states when NOT to use it (e.g., versus find_annotation_usages for a single annotation), so guidance stops short of the 5-level routing clarity.

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

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

With no annotations, the description carries the full burden and does well: it discloses output shape (hierarchical), edge-case filtering (local/anonymous classes excluded, record components as first children), and the error behavior for out-of-range maxResults (INVALID_PARAMETER). It does not state cost/latency or behavior for a nonexistent file path, keeping it from a 5.

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

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

Front-loads the purpose, then uses USAGE/OUTPUT labels for scannability, and every sentence (including the local-class exclusion) carries real information. Slightly fragmented line breaks and some redundant restatement of return contents keep it from a 5.

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

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

No output schema exists, yet the description explains the return structure, nesting, and what is deliberately omitted, plus the load_project precondition. For a 3-parameter read tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so filePath, maxResults and includePrivate are already fully documented. The description's mention of the maxResults valid range and INVALID_PARAMETER outcome largely restates the schema, and it never mentions includePrivate — baseline 3 applies.

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

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

States a specific verb and resource ('Get all symbols') plus the concrete contents (types, methods, fields) and scoping ('in a source file'). This lets an agent distinguish it from project-wide siblings like search_symbols, though no sibling is named explicitly.

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

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

Gives a clear usage line ('Provide a file path to get all symbols in that file') and, importantly, a hard prerequisite ('Requires load_project to be called first'). It stops short of naming alternatives such as search_symbols for cross-file lookups, so no exclusions are stated.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.