schedule_shutdown

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

With no annotations, the description carries the full burden of behavioral disclosure. It does warn that 'Forced app closing can lose unsaved work,' which is a helpful side-effect disclosure tied to the forceCloseApps parameter. However, it omits other important behaviors such as parameter precedence (what happens if both 'at' and 'afterMinutes' are provided), whether scheduling overwrites an existing scheduled shutdown, or if administrator privileges are required. These gaps leave the agent uncertain about edge cases.

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 concise, consisting of two sentences. The first sentence states the primary purpose, and the second provides a critical warning. The 'Replaces an existing Windows Power MCP shutdown' clause is slightly confusing and may not add value for the agent, but it does not significantly bloat the text. Overall, it is well-structured and front-loaded with the core function.

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?

Given there is no output schema, the description should clarify what the tool returns upon success or failure, but it does not. It also fails to specify how the parameters relate—particularly whether 'at' and 'afterMinutes' are mutually exclusive or if both can be used simultaneously. Without this information, an agent may make incorrect assumptions about scheduling behavior. The warning about forced closing is useful, but the lack of parameter interplay details and return value expectations makes the description incomplete for reliable usage.

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 input schema already describes all four parameters with 100% coverage, so the baseline is 3. The description adds minimal parameter-related meaning—only the warning about forced closing relates to forceCloseApps but does not enrich the schema's own description. Since the schema handles parameter definitions adequately, the description does not need to compensate significantly.

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's purpose: 'Schedule a one-time Windows shutdown.' It uses a specific verb (schedule) and resource (shutdown), and 'one-time' helps differentiate from recurring tasks. However, it does not explicitly distinguish this from sibling tools like shutdown_now or postpone_shutdown, which could confuse an agent about which to choose.

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?

The description gives no guidance on when to use this tool versus alternatives. It mentions 'Replaces an existing Windows Power MCP shutdown,' which appears to be a legacy note rather than a usage condition. There is no mention of using this for delayed shutdowns versus immediate ones, or how it interacts with postpone_shutdown or cancel_shutdown. The agent must infer the usage context from the name and schema alone.

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