get_harbor_info

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description layers substantial context on top: the exact return shape ({registries: [...]}), the detail-call behavior ('status and storage come from a detail call and are null if it fails'), and the error contract ('returns {error, hint} rather than raising'). No contradiction exists — the readOnly annotation matches the [READ] prefix and status-retrieval semantics.

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?

Every sentence carries distinct information: purpose, return shape, two error behaviors, use cases, and the prerequisite. The critical 'what it does' is front-loaded in the first sentence, and the supplementary detail is compact and scannable without 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?

With no output schema present, the description carries the full burden of explaining return values — and it does, including nullable fields (status, storage_used_mb) and the failure path. Error cases (Harbor not enabled, detail call failing) and the prerequisite for a possibly-down Supervisor are all covered, making this complete for a read-only tool with one optional parameter.

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 optional parameter `target` is fully documented in the schema ('vCenter in config.yaml; omit for the default.'), so schema coverage is 100% and the baseline 3 applies. The description adds no new parameter-level detail beyond the 'on the Supervisor' context, which is acceptable because nothing about the parameter is left 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?

Opens with a specific verb+resource+scope: 'Get status of the embedded Harbor container registry on the Supervisor.' The [READ] prefix makes the operation type explicit, and the sentence 'it does not list repositories or images' differentiates it from any registry-related sibling. The primary use cases ('check registry health or find the push URL') further pin down what the tool is for.

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?

States concrete when-to-use: 'Use it to check registry health or find the push URL.' It names the prerequisite sibling explicitly — 'Run check_vks_compatibility first if the Supervisor may be down' — and excludes the adjacent use case of listing repositories or images. This gives an agent clear routing logic without needing to inspect other sibling tools.

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