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

Beyond the readOnlyHint annotation, the description discloses the return contract (verdict ready|blocked, one finding per check, severity levels, sentence plus evidence) and an important semantic rule that a warning or unreadable-evidence skip means NOT CHECKED rather than passed. It also enumerates what each check inspects, including thresholds like the 300 s drain timeout and 24 h memory window, which the annotation cannot convey.

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 and the NOT CHECKED rule are front-loaded, and every clause carries non-redundant information. The long inline enumeration of checks is dense and would scan better as a list, but it is not padding.

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 fully carries the return-value burden: verdict shape, per-check findings, severity vocabulary, and evidence semantics. For a three-parameter read-only diagnostic tool it leaves nothing an agent needs in order to call it or interpret its 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 parameters are already documented and the baseline is 3. The description adds real meaning for target_version by explaining that hop_plan blocks a minor skip, a downgrade, or a version outside the catalogue, effectively constraining the acceptable value; cluster_id/cluster_name selection logic is left entirely to 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 opening sentence gives a specific verb (check), a specific resource (Ankra-provisioned self-managed cluster), a specific input (target_version), and a scope qualifier ('without changing anything'). It also implicitly separates itself from upgrade_cluster, which actually performs the hop.

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 context of use clearly: a preflight before a version hop, and it notes that upgrade_cluster runs the same preflight first and refuses on a block, which tells the agent this tool is the diagnostic counterpart. It does not explicitly say when not to call it (e.g. for managed clusters or non-Ankra clusters), so it falls short of a full when/when-not/alternatives statement.

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