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.

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

With no annotations, the description carries the full burden and falls well short. It does not say whether an existing destination file is overwritten, whether partial transfers are resumable, what permissions are needed on either side, or how errors/failures are surfaced — all critical for a mutation/transfer tool.

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?

Two short sentences with the core action front-loaded; the compression note is brief and relevant. Slightly terse for a transfer tool, but nothing is wasted.

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?

A 5-parameter file-transfer tool with no annotations and no output schema needs more than this. Overwrite behavior, transfer durability, prerequisites (READY handle), and error semantics are all absent, leaving the agent unable to predict the tool's effects.

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 80%, so the schema already documents handle, direction, and the path parameters; baseline is 3. The description adds only that zstd compression is supported, which lightly touches the otherwise-undescribed `compression` param but never clarifies the 'auto' mode or the zstd/none trade-off.

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 (stream transfer) and resource (a regular file) with clear scope (local machine to opened remote target). It distinguishes itself from read/write/edit/ls/grep siblings by being the bulk-transfer tool, though the 'regular file' qualifier (excluding directories) is the only real disambiguation and no sibling is named.

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 phrase 'opened remote target' implies a prerequisite that the handle must already be READY, but no explicit when-to-use, when-not-to-use, or alternatives are stated. An agent must infer that this is for copying rather than reading/editing content.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the READY-handle prerequisite and that replacements must be exact, but says nothing about what happens when oldText is not found, whether edits are atomic, or permission requirements for a mutation.

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?

Three short sentences with the core action front-loaded and the prerequisite second. No filler, though the final sentence largely restates the schema's required nested fields.

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 mutation tool with no annotations and no output schema, the description covers the action, target, and prerequisite but omits failure modes, matching behavior, and what the call returns or changes. Adequate, not 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 description coverage is 67%, near the middle baseline. The description names oldText/newText, but this merely restates the nested schema's required fields, and it adds no format or matching semantics (e.g. uniqueness, multiline behavior) beyond the schema.

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: 'Apply exact text replacements to a file on an opened remote target.' An agent can distinguish this from cascade_remote_read, cascade_remote_grep, etc., but the description does not explicitly separate it from the closely related cascade_remote_write sibling.

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?

Gives one prerequisite ('Requires a READY handle'), which is useful context. However, it offers no guidance on when to choose editing over cascade_remote_write or which sibling handles other mutations, leaving the choice to inference.

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

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

With no annotations, the description carries the full burden. It discloses the READY-handle state requirement, a genuine behavioral trait, but says nothing about return format, how limit interacts with results, or whether this is a read-only operation. Partial disclosure only.

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?

Two tight sentences with the core purpose front-loaded and the precondition immediately after. No filler or redundancy.

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 fully documented 4-parameter read tool with no output schema, the description covers purpose and one precondition. It stops short of clarifying result behavior or routing against the many remote siblings, leaving modest gaps.

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 path, limit, handle, and pattern are all documented in the schema itself. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 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 (Find) and resource (files matching a glob pattern) scoped to a remote target, which is clear. It doesn't explicitly distinguish itself from the closely related sibling cascade_remote_grep, so an agent must infer that find is name/path matching rather than content search.

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 supplies a precondition ('Requires a READY handle'), which is useful context, but gives no when-to-use guidance relative to alternatives like cascade_remote_grep or cascade_remote_ls. Usage is left to inference from the verb.

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

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

No annotations exist, so the description carries the full behavioral burden, yet it only discloses the READY-handle prerequisite. It does not state return format, whether pattern is regex by default (literal flag exists), pagination via limit, or what a non-READY handle error looks like.

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?

Two tight sentences with the core action front-loaded and the prerequisite second. No filler, though the second sentence is terse enough to feel under-informative rather than optimally dense.

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?

An 8-parameter search tool with no annotations, no output schema, and only 50% schema coverage needs more than two sentences. The description omits the regex/literal default, path scoping behavior, and result-limit semantics, leaving meaningful gaps.

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 only 50%, so the description should compensate, but it mostly repeats the required handle constraint ('READY handle'). It adds nothing for glob, path, limit, context, literal, or ignoreCase, leaving those to the partially-documented schema.

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 (search/grep) plus the resource (text content within files) and scope (opened remote target), making it clearly distinct from read/edit/ls siblings. It stops short of explicitly naming how it differs from cascade_remote_find, so an agent must infer the grep-vs-find boundary.

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?

Provides one concrete prerequisite ('Requires a READY handle'), which is real usage context. However it offers no guidance on when to use this versus cascade_remote_find or cascade_remote_read, leaving the alternative-selection decision implied.

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

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 the return shape (item names, DIR/FILE types, sizes), which is valuable since no output schema exists, but it says nothing about permissions, side effects, or how the optional path is resolved when omitted.

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?

Two tight sentences with the purpose front-loaded and the return contents following. No filler, though it is minimal enough that a little more scoping detail would not have hurt.

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 description covers return values, which matters since no output schema exists, but it omits what happens when the optional path is not supplied, how limit interacts with the listing, and pagination behavior. Adequate but with clear gaps for a discovery tool.

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 (path, limit, handle) are already documented in the schema, including the default of 500 and the READY handle example. The description adds no parameter-level detail beyond that, so the baseline of 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+resource ("List directory entries") scoped to "an opened remote target," which cleanly separates it from siblings like cascade_remote_read, cascade_remote_find, and cascade_remote_grep. It stops short of explicitly naming an alternative, so differentiation rests on the reader's inference from the sibling names.

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?

"On an opened remote target" hints that a READY handle is a prerequisite, which is mild usage context. However, there is no guidance on when to use ls versus cascade_remote_find or cascade_remote_grep, and no when-not conditions are given.

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

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

With no annotations, the description carries the full burden. It discloses the READY-handle precondition and the offset/limit line-based read model, but does not state read-only semantics, behavior on an invalid handle, or what a failed read returns. Useful but incomplete disclosure for a read operation.

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?

Three short sentences with the core purpose and the handle prerequisite front-loaded; nothing is padded. It is terse enough that a little more detail could fit without harming readability.

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?

There is no output schema, so the description should carry return-value expectations; it only hints at numbered lines via 'with line numbers' and says nothing about error or empty-file behavior. Adequate for invoking the tool, but thin for a tool with no structured return contract.

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%, with each of the four parameters documented (path, limit, handle, offset 1-based) directly in the schema. The description's 'offset & limit with line numbers' merely restates what the schema already provides, 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 ('Read a file from an opened remote target'), which clearly separates it from sibling listing/search operations like cascade_remote_ls, grep, and find. However, it does not explicitly name any sibling or contrast itself beyond the implicit file-contents scope.

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?

Provides a real prerequisite ('Requires a READY handle returned by cascade_target open'), which tells the agent when the tool is usable. It offers no when-not guidance and does not route the agent to alternatives such as cascade_remote_grep for searching or cascade_remote_ls for listing, so usage is only partially framed.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose two useful traits: the READY-handle prerequisite and automatic parent-directory creation. It stops short of stating the most consequential behavior for a write tool — whether existing file content is overwritten or truncated, and whether the operation is reversible.

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?

Three short sentences, each earning its place: purpose first, then the precondition, then the side benefit. No filler and no repetition of the field list.

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?

With no annotations and no output schema, the description should cover the mutation's side effects, and it omits the single most important one — overwrite behavior on an existing file. The auto-mkdir note is a nice addition, but an agent still cannot fully predict the state left behind.

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 handle, path, and content are already documented in the schema; baseline 3 applies. The description's mention of a 'READY handle' reinforces the schema's handle semantics but adds no format or syntax detail beyond it.

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 (write) and resource (file on a remote target) with the scope constraint that the target must be active. It is clearly distinct from a read tool, though it never explicitly contrasts itself with the sibling cascade_remote_edit, whose role (presumably partial/surgical edits vs full-content writes) an agent must infer.

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 prerequisite 'Requires a READY handle' gives a usable precondition for calling it. However, there is no explicit guidance on when to choose this over cascade_remote_edit or cascade_remote_bash for modifying remote files, so the write-vs-edit decision is left to inference.

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

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

With no annotations, the description carries the full burden. It does disclose meaningful behavior: open returns a target handle, close terminates one handle, disconnect terminates all handles, forget removes a remembered pinned target. But it is silent on authentication (the presence of a password parameter is never explained), the transient vs. pinned lifetime distinction, and anything about persistence of connections.

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?

One opening purpose sentence followed by a tightly packed action-by-action rundown. Front-loaded with the capability summary, every sentence carries a distinct action mapping, and there is no filler.

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 7-parameter, no-annotation connection-management tool with no output schema, the description covers action semantics well but leaves notable gaps: how credentials (password) are supplied, what transient vs. pinned actually means for connection lifetime, and what a nested target chain looks like. It also never positions itself relative to the cascade_remote_* tools that presumably consume its handles.

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% across 7 parameters, so the description must compensate. It fully glosses the action enum and indirectly implies the handle parameter ('returning a target handle', 'close a specific handle'). It says nothing about host, password, mode (transient/pinned semantics), cwd, or the target chain syntax, so compensation is partial.

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?

Opens with a specific verb set and resource: 'Discover, connect, and manage Docker and SSH targets,' which is concrete and actionable. It never mentions the cascade_remote_* siblings, so an agent must infer that this is the connection-management tool that those file/bash tools depend on. Clear purpose, but no explicit sibling differentiation.

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?

Gives explicit per-action routing: use list to inspect containers, open to establish a connection and get a handle, handles/status to inspect, close vs disconnect to tear down, forget to remove a pinned target. That is strong when-to-use guidance across the seven actions. However, it never states when to prefer this tool over the cascade_remote_* family, nor any prerequisites/exclusions.

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