windows_shell_open

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

Annotations only provide readOnlyHint=false, openWorldHint=false, etc., but no detailed behavioral traits. The description adds important behavior: the approval survives restarts until windows_shell_close, and notes that duration_seconds is legacy compatibility. This goes beyond the basic annotations and helps the agent understand persistence and parameter deprecation.

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 a single sentence that conveys the core action, persistence, and a parameter caveat. It is front-loaded with the primary purpose, and every clause adds value. No filler 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?

Given that this tool has a clear purpose, an output schema (which likely documents the result), and only two simple parameters, the description covers the main behavioral points. However, the purpose parameter is left unexplained, and there is no mention of what constitutes 'approval' or how it is handled. The description is adequate but not fully complete for a tool that triggers a user-approval flow.

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%, and the description provides only minimal parameter context: it mentions that duration_seconds is legacy compatibility, but does not explain the purpose parameter or its expected content. The purpose parameter is required but unexplained, leaving the agent to guess what information to provide. The description adds some value for duration_seconds but fails for purpose.

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 action ('Request one local approval for persistent Windows Shell authorization') and specifies the scope (persistent across restarts until closed). It distinguishes this from related tools like windows_shell_prepare, windows_shell_run, and windows_shell_close by focusing on the authorization/approval step.

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 explains when the tool is used (to request approval before shell operations, and that it persists until close), but does not provide explicit guidance on when NOT to use it or which alternative (e.g., windows_shell_prepare) might be preferred. The context of 'one local approval' implies a prerequisite step, but comparisons are not explicit.

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