mcs_wait_for_status

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the polling interval (every 5 seconds), timeout behavior, and return values (reached=true on success, reached=false with current status on timeout). This transparently conveys the blocking nature and outputs. It does not mention potential errors or side effects, but as a wait tool, these are less critical.

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 well-structured: a concise summary sentence followed by a clear argument list. The polling interval and purpose are front-loaded. It is slightly verbose in the summary (mentions replacing push notifications, which is useful context but not strictly necessary), but overall efficient and easy to scan.

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?

The tool has an output schema (per context signals) and the description explains the return behavior (reached true/false and current status on timeout). It covers the essential context: purpose, all parameters, polling behavior, and outcomes. Nothing critical for correct invocation is missing; it does not describe error handling, but for a wait tool this is acceptable.

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 0%, so the description must fully explain each parameter. It does so comprehensively: instance_name (server instance name or UUID), target_status (accepts 'running'/'stopped' or Chinese '运行中'/'已停止'), and timeout_seconds (default 300, range 5-1800). This provides meaning far beyond the bare schema, compensating completely for the lack of 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 description clearly states the tool waits for a server instance to reach a target status via polling, and explicitly ties it to confirming completion after start/stop/restart. This distinguishes it from sibling tools like mcs_instance_status (which likely just reads current status) and the mutation tools (start/stop/restart). The purpose is specific and unambiguous.

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 explicitly says to use this after start/stop/restart to confirm operation completion, and mentions it replaces the old 'background push notification' capability, giving clear usage context. However, it does not explicitly state when NOT to use it (e.g., for a one-off status check, use mcs_instance_status instead). The absence of an exclusion leaves some ambiguity but the primary use case is clear.

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