harbor_diagnose

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

Annotations already declare readOnlyHint=true, and '[READ]' merely restates that. 'Show partial failures' does add genuine behavioral value, indicating the tool reports degraded probes rather than aborting, but the description never explains what a partial failure looks like, whether probes run in parallel, or how long aggregation takes.

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 short sentence, front-loaded with the read tag and the core verb, with no filler. It is terse to the point of being telegraphic, which costs a little comprehension, but every word is load-bearing.

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 an aggregation tool with no output schema, two wholly undocumented parameters, and only readOnlyHint for safety context. An agent knows roughly what it touches but not what to pass or what shape the correlated result takes, so the definition is under-specified 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 description coverage is 0% and neither of the two parameters is mentioned in the description. 'target' in particular is highly ambiguous (a project, registry endpoint, or probe name?) and 'limit' is unexplained, so the description fails to compensate for the schema 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 names a concrete activity (correlate health, volume, GC and replication probes) that clearly implies an aggregate diagnostic across the domains covered by sibling tools like harbor_health, harbor_volumes and harbor_gc_history. It does not explicitly name those siblings or state that this tool replaces calling them individually, so it stops short of a 5.

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 when-to-use or when-not-to-use guidance and no mention of the alternative single-domain probes that an agent could call instead. 'Show partial failures' hints at a troubleshooting scenario but never tells the agent when this aggregation is preferable to harbor_health or harbor_volumes.

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