cascade_remote_bash

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

With no annotations, the description carries the full burden. It usefully discloses return values (stdout, stderr, exit code), timeout support, and that cancellation kills child process trees via pidfd/procfs. It omits the side-effect profile of arbitrary shell execution (it can mutate or destroy remote state) and says nothing about permissions or failure modes.

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?

Four short sentences, front-loaded with the core action and followed by return values and cancellation behavior. No filler, though the timeout clause is largely redundant with the schema.

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 a three-parameter tool with no output schema, the description covers action, return shape, timeout, and cancellation semantics, which is enough to invoke it correctly. It stops short of describing the prerequisite lifecycle that produces a READY handle or the risk profile of executing arbitrary commands.

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 100%, so all three parameters (handle, command, timeout) are already documented in the schema. The description only echoes the timeout-in-seconds semantics and adds nothing about handle format or command constraints, so the baseline 3 applies.

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?

States a specific verb and resource ("Execute a shell command on an opened remote target"), which is categorically distinct from the file-oriented siblings (read/write/edit/ls/find/grep/copy). However, it never names an alternative tool or explicitly contrasts itself against them, so differentiation is implicit rather than stated.

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 says "on an opened remote target" and the schema notes the handle must be READY, implying a prerequisite, but there is no guidance on when to prefer bash execution over cascade_remote_read/write/edit or the search siblings. No exclusions or conditions are given.

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