wait

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds one genuinely useful non-obvious behavior: a timeout never cancels the underlying operation. However, it does not say what happens to the caller on timeout (error vs. partial status), whether the call blocks, or what is returned, so the added context is thin.

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, front-loaded with the core purpose and followed by the key constraint. There is no filler, though the compressed phrasing "exactly one operation, cluster generation, backup or restore" reads awkwardly and could be clearer without adding length.

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 7 optional parameters, no output schema, and no per-parameter documentation, the description leaves important gaps: what the call returns when the wait succeeds or times out, and how the mutually exclusive target parameters interact with namespace. The one behavioral fact it gives (timeout does not cancel) is useful but insufficient for a tool of this 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% across 7 parameters, so the description must carry the load. It does add one meaningful rule not present in the schema: exactly one target must be specified among operation/cluster generation/backup/restore. It says nothing about namespace, the role of timeout (default 120, max 600), or how "generation" pairs with "cluster," leaving substantial gaps.

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 ("wait") plus an enumerated set of target resources (operation, cluster generation, backup, restore), so an agent can tell this is a blocking/poll-until-done tool. It does not differentiate itself from adjacent polling siblings such as operation_get, operations_list, or cluster_operations_list, which keeps it from 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 explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative (e.g., use operation_get for a one-shot status check, wait for blocking until terminal). The only implied guidance is the phrase "exactly one," which hints at single-target selection but is never stated as a rule.

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