heap_histogram

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

readOnlyHint=true already communicates that the call does not mutate state, so the description does not need to restate that. It does add useful scoping information by specifying the top-N heap-object occupancy, which is a snapshot-style read; however, it does not disclose potential side effects such as performance cost or whether a full GC might be triggered to compute the histogram.

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 one short sentence with no filler and front-loads the core concept of heap object occupancy with Top-N. It earns high marks for economy, though it is slightly under-specified as a definition because it omits usage context.

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 read-only tool with an output schema and clear parameter names, the minimal description plus annotations may let an agent call it successfully. However, the definition lacks any context about when to use it, why an agent would choose it, or how the histogram is produced, leaving a clear gap in operational context.

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

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

With 0% schema description coverage, the description must carry parameter meaning. It explains 'top' through the Top-N phrase, but it does not explicitly describe 'pid' as the target JVM/process whose heap is inspected. For two simple parameters, the minimal semantics are adequate, but the description only partially compensates for the missing schema descriptions.

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

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

The Chinese description '堆内对象占用 Top-N' communicates that the tool returns the top-N heap objects by occupancy, which clearly distinguishes it from sibling tools gc_stat and thread_dump. The only reason it is not a 5 is that it uses a nominal phrase rather than an explicit verb such as 'get' or 'return', leaving the exact operation implicit.

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 gives no guidance about when to choose heap_histogram over gc_stat or thread_dump, and it does not mention typical use cases such as memory-leak or large-object analysis. There is no 'when/when-not' or alternative routing, so an agent must infer usage from the name alone.

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