Execute PowerShell

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

Annotations already disclose destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the description doesn't need to repeat those. The description adds a caution to 'Verify changes afterward,' which is helpful, but it doesn't elaborate on side effects, permissions, or potential system impact beyond what the annotations imply. Given the annotations carry the risk profile, the description's additional behavioral context is minimal but appropriate.

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 three concise sentences: the primary action, a list of appropriate use cases, and a verification instruction. The purpose is front-loaded in the first sentence. No filler or redundancy. Every sentence adds value, making it highly efficient.

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?

For an arbitrary command execution tool, the description covers the essential aspects: what it does, when to use it, and a caution to verify. It does not describe return output or error handling, but there is no output schema, so that is not strictly required. Given the complexity of the tool and the existence of many specific siblings, the description is sufficiently complete to guide an agent in selecting and using it appropriately.

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 description provides no detail about the parameters themselves. The input schema covers 'command' and 'cwd' with descriptions, but 'timeoutSeconds' lacks a description (schema coverage is 67%). The description does not compensate for this missing parameter information, nor does it add any meaning beyond the schema for the existing parameters. Since the coverage is moderate but not high, the description should have at least mentioned the timeout or working directory behavior, but it doesn't.

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 primary action: 'Run an arbitrary PowerShell command on this Windows PC.' It specifies the resource (PowerShell on Windows) and the scope (arbitrary). It also lists common use cases (local development, package installation, system configuration, services, processes) and explicitly distinguishes from more specific tools by saying 'tasks not covered by a more specific tool,' which differentiates it from the sibling tools.

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 explicitly provides usage guidance: 'Use for local development, package installation, system configuration, services, processes, and tasks not covered by a more specific tool.' This tells when to use it and implies when not to use it (when a more specific tool exists). It also adds a safety instruction: 'Verify changes afterward,' which is a clear directive for safe usage.

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