Run shell command

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

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, which already convey it's a potentially destructive, non-idempotent mutation. The description adds useful details: captures stdout/stderr separately, supports streaming with progress notifications, cwd restriction, and default timeout from env var. However, it doesn't mention that commands could have side effects beyond the hint, or what happens on timeout (e.g., process killed?). It doesn't describe security implications of running arbitrary commands. Adding these would increase transparency, but given annotations already flag destructiveness, the description adds moderate value.

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 compact, three sentences, each conveying a distinct point. The first sentence states the core behavior with stream capture. The second explains streaming. The third states a critical constraint. No fluff, well organized.

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 4 parameters, all documented in schema, and the description covers the key constraints (cwd restriction, streaming behavior, timeout default). However, no output schema is present, and the description does not describe the return value format (e.g., how stdout/stderr are returned, exit code, error handling). For a tool that runs arbitrary commands, the agent would benefit from knowing the response structure. Given destructiveHint, it might also be good to state that the command may mutate state. Overall, it's functional but not fully complete.

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 100%, so all four parameters (command, cwd, stream, timeoutMs) are documented in the schema itself. The description adds context for cwd (must be inside allowed root) and stream (sends progress notifications), which supplements the schema. It also mentions timeout default from env var. This goes slightly beyond schema, but because the schema already describes each parameter adequately, the description's added value is modest. Baseline 3 is appropriate.

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 runs a command with the user shell, capturing stdout and stderr separately. It distinguishes itself from other file/system tools, though it doesn't explicitly differentiate from a potential 'run_script' sibling (none exist). It's specific about behavior (captures streams, supports streaming).

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 mentions the cwd restriction (must be inside allowed root unless environment variable overrides), which is a usage constraint. However, it does not explicitly state when to use this vs alternatives (e.g., when to use read_file/write_file instead). It provides no guidance on when not to use it, such as for read-only operations. The streaming option is explained but no guidance on selecting it. Overall, context for choosing this tool is lacking.

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