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

With no annotations, the description must carry the full behavioral burden. It usefully discloses the side effect of stopping the MAT helper process, but leaves major questions open: whether the underlying dump file is deleted or retained, whether the report_id becomes invalid afterward, and whether the operation is reversible.

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 action is front-loaded and the sentence is tight; the bilingual mirror doubles the text length but adds no redundant concepts. No filler 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?

An output schema exists so return values need not be explained. For a two-parameter lifecycle tool the description covers the action and the one non-obvious side effect; only the provenance of report_id and the fate of the dump file are missing.

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

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

Schema description coverage is 0%, so the description has to compensate for both parameters. It fully explains stop_service's effect, but report_id gets no explanation at all (presumably an ID from open_heapdump or list_heapdumps) — half the parameters remain undocumented.

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 ("Release a heap dump handle") that pairs cleanly with the sibling open_heapdump, so the agent can infer the open/close lifecycle. It does not explicitly name or distinguish itself from get_heapdump_status or list_heapdumps, but the intent is 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?

Usage is only implied: you release a handle after opening one. The one piece of explicit guidance is conditional on a parameter ("Set stop_service=true to also stop the MAT helper process"), with no statement of prerequisites, when not to call it, or how it relates to get_heapdump_status.

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?

Annotations already flag this as destructive, non-idempotent, and not read-only, and so the description goes further by disclosing the exact risk: a live dump triggers a Full GC and may pause the target JVM. It also states the output location default (current working directory) and that the result is auto-opened for MAT parsing, which an agent cannot infer from the annotations.

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 front-loaded: purpose first, then the confirm protocol, then the safety warning. The main waste is that the entire block is repeated verbatim in Chinese, roughly doubling length without adding information for an English-reading agent.

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 destructive, non-idempotent tool this covers the essentials an agent needs to act safely, and the presence of an output schema removes any obligation to describe return values. The remaining gaps are minor: pid and timeout semantics, and what happens if the dump fails or disk space is insufficient.

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?

With 0% schema description coverage, the description carries the full burden, and it does well for confirm (default false, preview vs execute) and output_dir (defaults to cwd). However, pid is only gestured at via "preview the target," and timeout is mentioned solely as something previewed, with no units or meaning (per-operation? per-phase?) — half the parameters remain semantically thin.

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 and resource ("Capture a LIVE heap dump from a running JVM") plus the chained side effect ("start MAT parsing"). The emphasis on LIVE and "running JVM" implicitly separates it from open_heapdump, which operates on existing files, so 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?

It spells out a concrete two-phase calling protocol: call with confirm=false to preview target/output dir/disk space/timeout, then confirm=true to execute. That is strong contextual guidance, but it never names the alternative (open_heapdump, list_java_processes) for the case where the agent wants to attach to an existing dump or discover a pid 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 are provided, so the description carries the full behavioral burden. It discloses that this is a status/progress query, but it does not explain permissions, whether parsing is asynchronous, polling expectations, possible status values, or failure behavior for an invalid report_id.

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 short and front-loaded, with the core purpose stated immediately. However, the second sentence is a Chinese translation that duplicates the English content without adding semantic value for an agent.

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?

This is a simple one-parameter query with an output schema, so return-format details are not required in the description. Still, it omits report_id guidance, usage context, and basic behavioral expectations, leaving it adequate but incomplete.

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 tool has one required parameter, report_id, and schema description coverage is 0%. The description only says 'for a heap dump report' and does not explain where report_id comes from, its expected format, or whether it matches IDs returned by dump/list tools.

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 ('Get') and resource ('parse status and progress for a heap dump report'). Sibling tools are list/open/close/dump operations or MAT analytics, none of which is a status/progress query, so an agent can distinguish this tool by purpose even without an explicit sibling reference.

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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternatives. The word 'status' implies checking an existing report, but the description does not say when to poll this versus using list_heapdumps or other report 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. Saying the result includes status is useful, and 'list' implies a read-only operation, but it doesn't clarify whether it returns only currently-open dumps or all known ones, nor anything about ordering, limits, or permissions.

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

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

Two short sentences with the resource and scope front-loaded and no filler. The bilingual duplication doubles the length, which is defensible for localization but doesn't add information for a single-language agent.

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 simple, parameterless discovery tool with an output schema documenting the return shape, the description covers what is needed to call it correctly. The remaining gap is the relationship to open/close/status siblings, which would help an agent place it in the workflow.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. No parameter information is repeated or wasted.

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 ('List heap dumps') plus a scope qualifier ('known to this MCP server') and notes that status is included. It is clear on its own, but it does not distinguish itself from siblings like get_heapdump_status or open_heapdump, which an agent must still infer.

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 is only implied: listing is the natural discovery step before open_heapdump and get_heapdump_status, but the description never says when to call this versus those siblings or whether the listing is a prerequisite. No exclusions or conditions are given.

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 annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavior beyond that: it returns pid, main class, command, and masked JVM arguments, and it explicitly excludes the managed MAT helper process.

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 English description is front-loaded and efficient, first stating the purpose and then adding return details and the exclusion. The full Chinese translation duplicates the same content, which is useful for localization but prevents a perfect conciseness score because half the text is redundant for an agent.

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 is complete for a zero-parameter discovery tool. It explains what is listed, what is returned, that JVM arguments are masked, and that the managed MAT helper is excluded; the output schema can carry the full return structure.

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 tool has zero parameters, so there is no parameter semantics to explain. The baseline score for a no-parameter tool is 4, and the schema is empty and complete as expected.

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 action and resource: discovering local Java processes that can be attached for a live heap dump. It also gives scope boundaries by saying the managed MAT helper is excluded, which helps distinguish it from sibling tools that list heap dumps or operate on existing dumps.

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 context is clear: this is for finding local Java processes that can be attached for a live heap dump. It does not explicitly name follow-up alternatives such as open_heapdump or dump_java_heap, but the attach-for-live-heap-dump framing gives the agent enough context to infer the workflow.

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 does disclose the core behavior - it counts active/idle connections and flags connections held longer than thresholdMs - but says nothing about whether it is read-only, what permissions or preconditions (loaded report) are needed, or how costly the scan is.

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 English sentence is well front-loaded and waste-free, but the full Chinese translation doubles the length without adding information for an agent parsing English, diluting density.

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?

An output schema exists, so return values need not be explained, and the tool is small. Still, for a diagnostic tool with a mandatory report_id and 0% schema coverage, the description should at least identify what the report reference is and whether the operation is a safe read.

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

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

Schema description coverage is 0%, so the description must compensate. It does define thresholdMs semantically (connections held longer than this are treated as leaked), which is real added value, but report_id - the only required parameter - is given no meaning at all beyond its name.

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 pairs a specific verb, 'Diagnose', with a specific resource, 'DB connection pools', and enumerates the output (active/idle counts, leaked connections). No sibling tool covers connection pools, so it is distinct in practice, though the description never explicitly contrasts itself with the other mat_* diagnostic 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?

Usage is only implied: an agent can infer it should call this when investigating pool exhaustion or leaks, but there is no explicit when-to-use, no prerequisites (e.g. that a parsed report must exist), and no guidance on when mat_leak_suspects or mat_top_consumers would be the better choice.

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 disclose one important trait: the operation is async. However, it gives no indication of how results are retrieved afterward (job handle, status tool, polling), expected runtime/cost, or whether repeated invocations on the same report_id reuse prior work. For an async aggregate of three expensive scans, those gaps matter.

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

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

Two compact sentences with the action front-loaded and no filler; the key 'async' qualifier and the aggregation list both appear immediately. The full English/Chinese duplication is redundant for a single-language reader but is a standard bilingual convention, so it is not a real defect.

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?

An output schema exists, so return-value shape need not be explained. Still, for a multi-analysis orchestration tool with an async contract and three undocumented parameters, the description omits the follow-up path (how to collect the async result) and the meaning of the tuning options, leaving an agent unable to call it well without opening the 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 description coverage is 0% and the description mentions no parameters at all. Three parameters exist — report_id, onlyRisky (default true), and culpritPct (default 30) — and the description provides no meaning for any of them, notably leaving the semantics of onlyRisky and culpritPct entirely unexplained.

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 ('Run comprehensive OOM diagnosis') and enumerates exactly what it aggregates (leak suspects, SQL-in-threads, dominator analysis), which implicitly sets it apart from the individual sibling tools. It does not explicitly name those siblings, so an agent must infer the relationship, but the purpose itself is 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 enumeration of the three analyses implies this is a one-call alternative to mat_leak_suspects / mat_sql_in_threads / mat_dominator, but no sibling is named and there is no explicit when-to-use/when-not guidance. Nothing says whether to prefer this aggregate for a first-pass triage versus calling the targeted tools for a focused question.

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 the full burden. It does disclose implicit ordering ('biggest retained-heap dominators') and the hierarchical drill-down model, but says nothing about whether results are truncated, paging behavior, or cost of the traversal.

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

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

A single compact sentence pair with the core purpose front-loaded, plus a bilingual mirror that adds no new information cost. No filler text, though the duplicated Chinese rendering doubles length for no semantic gain.

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?

Output schema exists so return values needn't be described, and the drill-down mechanic is covered. But for a 3-parameter tool with zero schema descriptors and no annotations, leaving report_id and top unexplained leaves an agent guessing about inputs.

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

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

Schema coverage is 0%, and the description explains only 'parent' (pass an objectId to drill down). The required 'report_id' and the 'top' limit (default 20) are never addressed, and the schema's default value 'ROOT' for parent is not mentioned either.

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: 'Dominator tree: list biggest retained-heap dominators' with drill-down by parent. An agent can distinguish this from mat_histogram or mat_leak_suspects by the 'dominator tree' framing, 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 concrete mechanics for one workflow ('drill down by passing parent=objectId') but never says when to choose this over mat_histogram or mat_leak_suspects, nor any prerequisites such as needing an open heapdump report 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 are provided, so the description carries the burden. It discloses useful behavioral traits: default Top-20, configurable sort, and objectSet reuse of prior results. It stops short of stating the safety profile, whether it reads vs mutates, or cost of computation, but as an analysis tool with an output schema this is adequate.

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

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

The English sentence front-loads what the tool produces and then the parameters, with no wasted clauses. The mirrored Chinese sentence duplicates the same content, which is helpful for some audiences but adds length without new 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?

With 4 parameters, no annotations, and an existing output schema, the description covers most of what is needed to call it, but the unexplained required report_id and the missing when-to-use guidance leave a meaningful gap for correct selection.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for top (override default N), sort (the three dimensions), and objectSet (reuses prior OQL/RS result), but leaves report_id and the sort default (retained) unexplained, so it only partially fills the gap.

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 resource (class histogram) and the sort dimensions (shallow/retained/count), so an agent knows it produces a ranked class table. It doesn't explicitly contrast with siblings like mat_dominator or mat_top_consumers, but the histogram framing is reasonably distinct.

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 conveys that Top-N (default 20) applies and that top overrides it, and that objectSet reuses a prior OQL/RS result. However, there is no guidance on when to pick this over alternative analysis tools (mat_dominator, mat_top_consumers) or what report_id must reference.

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 disclose two real traits: the operation is asynchronous and it is SLOW (may take a minute). It omits how results are retrieved after the async call (presumably via get_heapdump_status) and any permission or failure behavior.

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 English text is front-loaded and efficient: verb, return shape, then the latency warning. The full bilingual duplication roughly doubles length without adding information, a minor cost.

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?

An output schema exists so the return shape needn't be explained, and the SLOW/async warning is valuable. But for an async tool, the description leaves a real gap: it never says the result must be polled or where to obtain it, which an agent needs before calling.

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 report_id has 0% schema description coverage, and the description does not explain what it is (a heapdump/report identifier) or where it comes from. Unlike the 0-parameter baseline of 4, this param needs prose support that is absent.

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: runs LeakHunter and returns leak suspects with retained size and description. The resource is distinct from siblings like mat_dominator or mat_histogram, though it never explicitly contrasts itself with them.

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

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

No guidance on when to reach for this versus mat_dominator, mat_top_consumers, or other analysis tools; the leak-hunting framing implies usage but names no alternatives or prerequisites (e.g., that a heapdump must already be opened to supply report_id).

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. 'Inspect' implies a read operation and the listed aspects clarify what kind of information is returned, but it does not explicitly state read-only behavior, prerequisites, or whether any side effects exist.

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 and extremely compact, with the core action and inspected categories stated first and the required object id called out immediately. The bilingual repetition is slightly redundant but does not introduce unnecessary noise.

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 presence of an output schema reduces the need to explain return values, and the description does list inspected object aspects. However, for a tool with two required parameters, zero schema description coverage, and no annotations, omitting the required 'report_id' parameter is a significant completeness 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 0%, so the description must explain both parameters. It clarifies that 'id' is an object id, but it omits 'report_id', which is required by the schema, leaving one of two required parameters undocumented in the description.

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

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

The description uses a specific verb, 'Inspect', and resource, 'a single object', then enumerates the inspected aspects: class, fields, statics, in/out refs, and GC root. This distinguishes it from aggregate siblings like mat_histogram or mat_dominator, though it does not explicitly name those alternatives.

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 implies the tool is for inspecting one object when an object id is available, but it does not explicitly state when to use this tool versus siblings such as mat_path2gc, mat_histogram, or mat_dominator. There are no stated exclusions or 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 burden and does well: it discloses the performance cost, the reusable resultSetId, and the security-relevant fact that OQL can read arbitrary heap strings (treat results as private). It stops short of stating read-only semantics, timeout behavior, or how limit interacts with execution cost.

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 lead sentence is well front-loaded with the operation and the 'slow' warning. However, the entire content is repeated verbatim in Chinese, roughly doubling length without adding information for most readers.

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?

An output schema exists, so return values are covered, and the description covers purpose, cost, and privacy. For a 5-parameter query tool with zero schema descriptions and no annotations, the missing explanation of limit/sort/view and of report_id binding leaves real 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 0% — parameters are bare titles only. The description gives concrete query-string examples for 'q', which is genuinely useful, but says nothing about report_id, sort, view, or limit, leaving four of five parameters undocumented anywhere.

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 ('Run an OQL query against the heap') and adds the key outputs (rows + resultSetId). It is clearly distinct from siblings like mat_histogram or mat_dominator, though it never explicitly contrasts itself with them.

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 parenthetical '(slow!)' implicitly steers agents toward cheaper prebuilt tools when possible, and the privacy warning implies care. But there is no explicit when-to-use / when-not-to-use statement or named 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 are provided, so the description carries the full burden; 'Show' does imply a non-destructive read of an existing heapdump, which the agent can infer. However, it never states the prerequisite that a heapdump must already be opened (report_id from open_heapdump) or what happens on an invalid/closed report — material gaps for a tool positioned as the mandatory first step.

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 purpose statement is front-loaded and dense with useful specifics, and the ordering rule follows immediately. The only waste is the full bilingual repetition, which doubles length without adding information for a single reader.

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?

An output schema exists, so return values need not be described, yet the description still summarizes them, plus it establishes the call-first convention. What is missing is the lifecycle context: that it operates on a heapdump opened via open_heapdump and requires a valid report identifier.

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

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

Schema description coverage is 0% and the single parameter report_id is never mentioned in the description — not its meaning, nor where to obtain it (presumably from open_heapdump). With no schema text to fall back on, the description should have explained this identifier, so it fails to compensate for the coverage gap.

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?

Specific verb 'Show' plus the resource 'heap overview', followed by an explicit enumeration of contents (used/committed/live heap, object/class/classloader counts, JDK version, leak suspect count). This makes it clearly distinguishable from siblings like mat_histogram, mat_dominator, and mat_leak_suspects, which cover subsets of these facts.

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?

'Always call this first to understand a heapdump' gives an explicit ordering rule relative to every sibling, which is strong actionable guidance. It stops short of naming exclusions or follow-up paths (e.g., 'then use mat_leak_suspects for suspect detail'), so it is clear context without full alternative 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?

Annotations already declare readOnly/idempotent/closed-world, but the description adds real behavioral context: synchronous execution, the prerequisite that the dump be parsed (status=DONE), and the result shape (up to five linear paths plus MAT's path tree). It doesn't discuss cost/latency on very large heaps, which keeps 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 and dense with no filler sentences, but it is a single packed paragraph where the upstream-flow sentence partially repeats ids of tools already listed in the alternative sentence; slightly trimming would improve scanability.

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 an output schema, full param coverage, and safety annotations already present, the description covers exactly what structure can't: prerequisite state, upstream source of the identifier, and sibling routing.

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 object/report_id/excludeWeakSoft semantics are already fully documented, including the no-hex-id constraint and the weak/soft reference behavior. The description only restates where object ids come from, adding little 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?

States a concrete verb and resource ("shortest reference chains from one object to GC roots") plus the intent (explain why the object is still reachable), which an agent can distinguish from mat_dominator or mat_leak_suspects 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 upstream flow (obtain an id from mat_object/mat_histogram/mat_dominator/mat_leak_suspects, confirm with mat_object, then call this) and names two alternatives with the conditions that select them (mat_dominator for subtree retention, mat_leak_suspects when no specific object exists).

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?

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds genuinely new behavior: results are sorted risky-first then by retained heap, and heartbeat/validation statements are filtered by default. It omits anything about result size limits, pagination, or truncation on large dumps, which for a scan tool is a remaining 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?

Front-loaded with the purpose and prerequisite in the first two sentences, then the filtering semantics. The enumeration of every returned field is wasted space given an output schema exists, but the rest is dense 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?

With an output schema present, the return-value restatement is redundant, and prerequisites, default filtering, and sort order are all covered. Missing only operational details such as how many rows come back or behavior on a huge dump.

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's explanation of onlyRisky and its example statements largely restates the parameter's own schema description rather than adding new semantics; report_id's prerequisite is the only real added value.

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 ('Read-only scan of thread stacks for JDBC PreparedStatement objects and SQL strings') with a concrete investigative goal (heavy queries held by threads at OOM time). This clearly distinguishes it from siblings like mat_threadlocals (thread-local contents) and mat_oql (arbitrary queries).

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 triggering context ('spot long-running or heavy queries held by threads at OOM time') and a hard prerequisite (report_id of a parsed dump with status=DONE). It does not explicitly name alternative tools or say when to prefer e.g. mat_oql, so it stops short of full alternative 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 behavioral burden. It discloses the default grouping by valueClass and the alternative grouping by thread, but it omits whether the operation is read-only, any report prerequisites, permission needs, or other side-effect details.

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 short and front-loaded, with the grouping behavior and leak-finding use stated immediately. The bilingual repetition adds length without adding new information for an English-reading agent.

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 tool is simple and has an output schema, so return details are not required. Still, with no annotations and 0% schema coverage, the description should explain the required report_id and any prerequisite about opening a report, which it does not.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It explains groupBy values and default well, but it never explains the required report_id parameter, its expected format, or where it comes from.

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

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

The description uses a specific verb, 'Inspect', and a specific resource, 'thread locals', and states the grouping options. It is clearly about ThreadLocal inspection, though it does not explicitly distinguish itself from siblings such as mat_threads.

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 clear usage context: 'Useful for finding thread-local leaks.' However, it does not state when not to use it or name alternative sibling tools for related diagnostics.

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 must carry the behavioral load. It does disclose the return shape of list mode and the hierarchical drill-down order (threads → frames → locals), which is valuable, but says nothing about cost (MAT report parsing is expensive), prerequisites (report must be loaded/open), or whether repeated calls across reports are expected.

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

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

A single front-loaded sentence that moves from the default listing to progressive drill-down, so the common case is stated first. The full bilingual duplication doubles the length without adding information, 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?

An output schema exists, so return values need not be explained, and mode selection is covered. However, it omits that report_id refers to a previously opened heap dump managed by siblings (open_heapdump/list_heapdumps), which is the main thing an agent could get wrong before calling.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for two of three parameters: it clarifies thread is an id string and frame is an index, and that frame is only meaningful together with thread. report_id is left to the schema's title alone, which is a minor but real gap.

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 ('List threads') and enumerates the fields returned (name/state/daemon/frameCount), plus the two drill-down modes. It does not name the closely related siblings (mat_threadlocals, mat_sql_in_threads, mat_object), so the agent must infer differentiation from mode semantics 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?

Usage is made conditional in a usable way: pass thread=id to get stack frames, then additionally pass frame=idx to get frame locals. That is a clear when-to-use signal for each mode, but there is no guidance on when to prefer mat_threadlocals or mat_sql_in_threads, and no exclusions.

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?

Annotations already declare readOnlyHint, idempotentHint, and closed-world; the description corroborates rather than contradicts ('Read-only'). It adds useful context beyond annotations: the report's content scope and the hard prerequisite that parsing must have reached status=DONE. It omits depth/limit or pagination behavior for the object list, which is the only remaining 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?

Four sentences, each doing distinct work: purpose/content, placement in the workflow, sibling exclusions, and the DONE prerequisite. Front-loaded with the core definition before the routing advice.

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 single-parameter read tool with an output schema, full annotation coverage, and documented prerequisites, nothing an agent needs to select or invoke it correctly is missing. Return-value shape is handled by the output schema, so the description rightly does not repeat it.

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?

Only one parameter, and schema coverage is 100% — the schema already documents report_id including the status=DONE requirement verbatim. The description restates the same prerequisite without adding format or sourcing detail beyond it (e.g. that it comes from open_heapdump or dump_java_heap). Baseline 3 is appropriate since the schema carries this fully.

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 ('Read-only Top Consumers report') and enumerates exactly what it returns: biggest individual objects plus retained-size breakdowns by class, class loader, and package. This is clearly distinguishable from mat_histogram and mat_dominator, which are named.

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 explicit routing: use after mat_overview as a 'who is using the most memory' overview, use mat_histogram for a sortable per-class list, use mat_dominator to walk the graph downward from a parent object. Both alternatives and their selecting conditions are named, plus a prerequisite (report_id of a DONE parse).

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 present, the description carries the behavioral burden and does well: it discloses that MAT indexing runs in the background, that the call returns immediately with status=PARSING, and that completion must be polled. It omits error behavior for a missing/invalid path and any resource-lifecycle hint (close_heapdump), 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?

The English text is two tight, front-loaded sentences with the follow-up instruction last, so nothing is wasted. The full Chinese mirror doubles the length without adding information, which is defensible for a bilingual audience but is redundant text by strict conciseness standards.

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?

An output schema exists, so return details needn't be explained, and the async contract plus polling instruction covers the non-obvious part of a one-parameter tool. What remains missing is failure handling and the related lifecycle step (closing the opened dump via close_heapdump).

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

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

Schema coverage is 0% and the single 'path' property has only a title, so the description must compensate. It adds two meaningful constraints absent from the schema: the path must be absolute and must point to a local .hprof file, which is exactly the information an agent needs to form a valid argument.

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 (open a local Java heap dump), names the accepted format (.hprof), and distinguishes itself from the listing/parsing siblings by being the entry point that produces a report_id. An agent can tell it apart from get_heapdump_status or list_heapdumps 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 describes the follow-up workflow: poll get_heapdump_status until DONE, which tells the agent exactly what to do after the call. It doesn't state when not to use this tool (e.g., when a dump is already open or when dump_java_heap should be used first), so it stops short of full routing guidance.

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