MSAW

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

Annotations already set destructiveHint=true and non-idempotent. The description adds valuable context beyond that: concurrency behavior, the workspace-vs-global scope constraint, and precise output truncation policy (last 10 lines, 1500 chars, one global budget). No contradiction with annotations; it enriches the behavioral picture.

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 sentences, each fact-dense and front-loaded with the core purpose. The additional behavioral notes are placed after the purpose, and the output-routing note is last. No wasted words, though a slightly shorter version could combine scope and output details.

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 output schema exists, so return values need not be detailed, and the description does describe default truncation and the escape hatch (result_read). However, it leaves timeout and concurrency semantics unexplained, and does not address error scenarios or what 'most useful stream' means. Given the tool complexity, more parameter-level detail would improve completeness.

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 20% (targets has a description). The description reinforces that targets come from hosts_list but does not explain command, timeout, concurrency, or full_output beyond defaults. For low schema coverage, the description should compensate, but it only adds meaningful detail for one out of five parameters.

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 opens with a specific action 'Run the same shell command concurrently on one or more configured SSH hosts' – a clear verb-resource pair that immediately distinguishes this from siblings like hosts_list (listing hosts) and shared_read/shared_write (shared storage). The concurrency and multi-host scope add precision.

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 clear prerequisite ('targets must contain host IDs from hosts_list') and points to an alternative for full output ('Use result_read for undisclosed or full output'). It does not explicitly list when-not-to-use cases for other siblings, but the purpose is distinct enough that context is clear. Only one alternative is named, so not a full 5.

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?

The description adds value beyond the annotations by disclosing the transfer mechanism: resumable rsync with SCP fallback. With destructiveHint=true already declared, it is not required to restate destructiveness, but it does not clarify overwrite behavior or what exactly happens to existing files in the destination.

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 tightly written sentences. The primary purpose is front-loaded, and the fallback mechanism is stated second without any filler. Every word earns its place.

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 presence of an output schema and annotations covers return values and the destructive safety profile. The description covers the core operation and transfer fallback. However, parameter semantics remain thin for shared_path and full_output, and overwrite/destination behavior is left ambiguous, so it is 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 description coverage is 0%, so the description must compensate for the five undocumented parameters. It gives a high-level mapping between host workspace and shared workspace, which helps with remote_path/shared_path, but it does not explain host_id, timeout, or full_output. This is insufficient given the low coverage.

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 names a specific verb ('Pull'), a clear resource ('file or directory'), and explicit source/destination pair ('one host workspace' -> 'local shared workspace'). This directly distinguishes it from the opposite-direction sibling host_push_from_shared.

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 clearly conveys the intended use case: copying from a host workspace into the local shared workspace. It does not explicitly name alternatives or state when not to use it, but the directional wording provides enough context to route an agent.

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?

Annotations already mark the operation as non-read-only and destructive, so the description does not need to restate that. It adds genuine behavioral value by disclosing the transport mechanism: resumable rsync when available, falling back to SCP. It does not detail overwrite behavior, but the annotations cover the core safety profile.

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 concise sentences with no filler. The primary purpose and direction are front-loaded, followed by a useful implementation detail about rsync/SCP behavior.

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 presence of an output schema covers return values, and annotations cover the destructive nature. The main gap is parameter semantics: with five parameters and zero schema descriptions, an agent may not know what to pass for remote_path or what timeout/full_output control. The core selection and direction are clear, but full invocation guidance is incomplete.

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%, so the description must compensate for missing parameter explanations. It only implies the roles of shared_path and host_id through the overall sentence, and never explains remote_path, timeout, or full_output. The optional destination semantics are left entirely to inference.

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 uses a specific verb ('Push'), resource ('file or directory'), and a clear directional scope ('from the local shared workspace into one host workspace'). This inherently distinguishes it from the opposite sibling host_pull_to_shared and other shared/host 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?

It clearly states the transfer direction and target, giving an agent an obvious use case. However, it does not explicitly mention when not to use it or name alternatives such as host_pull_to_shared or shared_write.

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?

Annotations already declare readOnly and idempotent, but the description adds valuable behavioral context: it never returns secrets and exposes isolation and global-mode state, which help an agent understand the scope of the read. This goes beyond the annotation's simple safety hints.

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, front-loaded sentence that efficiently conveys the core purpose. It doesn't waste words, but it omits the parameter explanation, so it's not perfectly complete.

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 simple list tool with only one optional parameter, the description covers the main action and output content, but the missing parameter semantics leaves a gap. The output schema exists, so return format is partly covered, but the full_output flag remains ambiguous, making the description only moderately 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?

The single parameter full_output is completely undocumented in the description. With 0% schema description coverage, the agent has no clue what full_output=true vs false does. The description fails to add any meaning for the parameter.

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?

Description states a specific verb 'List' and resource 'SSH hosts', enumerating the included details: workspace, auth summary, isolation, and global-mode state. This clearly differentiates from siblings like host_exec or shared_list, which have distinct purposes.

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?

No explicit guidance on when to use this tool vs alternatives. It only states what it does, leaving the agent to infer usage. No mention of when not to use it or which sibling to prefer for other tasks.

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?

The description adds a useful behavioral guarantee around not exposing credentials and specifies that the tool checks SSH authentication and workspace access. However, it does not address the destructiveHint=true annotation or explain any side effects a 'test' may have on the remote host; this is a gap but not a direct contradiction.

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, front-loaded sentence with no wasted words. It states the action, target, scope, and an important security property efficiently.

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 is relatively simple, but the description is too sparse for fully reliable invocation: it lacks parameter semantics, usage guidance, and any mention of side effects despite destructiveHint=true. An agent can guess the required host_id, but timeout and full_output remain ambiguous.

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?

Parameter schema coverage is 0% and the description provides no explanation of host_id, timeout, or full_output. The parameter names are somewhat self-explanatory, but the description does not clarify what timeout bounds, what full_output returns, or how host_id relates to the configured hosts list.

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 uses a specific verb ('Test') and a specific resource scope ('one configured host's SSH authentication and workspace access'), so an agent can distinguish it from siblings like host_exec, hosts_list, and the shared/read/write tools. It also adds a clarifying constraint ('without exposing credentials').

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 implies this is a pre-flight or connectivity check for a configured host, but it does not explicitly say when to use it versus host_exec, hosts_list, or other siblings. There is no when-to-use, when-not-to-use, or alternative-tool guidance.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds valuable behavioral context by explaining the incremental/full modes, including that full 'may repeat content' and is 'clearly marked,' which goes beyond the structured metadata.

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 compact sentences with no filler. The core purpose is front-loaded, and the mode distinction is stated efficiently without repeating schema information.

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?

Annotations and the presence of an output schema lower the burden on the description, and the mode semantics are covered. However, the tool has three parameters with zero schema descriptions, and the description only partially explains them, so an agent may not know how to obtain or populate output_ref or how max_chars affects results.

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%, so the description must compensate for the three undocumented parameters. It explains the mode values (incremental vs. full), but it does not clarify output_ref semantics or max_chars behavior, leaving significant gaps for an agent trying to construct correct arguments.

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 a specific verb and resource: 'Read a cached tool result without rerunning it.' It does not explicitly distinguish this tool from sibling tools like shared_read, so it falls short of a 5, but the purpose is unambiguous.

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 implies when to use the tool—when a cached result exists and rerunning is undesirable—but it provides no explicit guidance on when to choose this over alternatives like shared_read, nor does it describe exclusions or prerequisites. This leaves the agent to infer the appropriate context.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the local-workspace scope and transfer purpose, but it does not disclose details such as whether path recursion is supported or whether hidden files are included; those are minor for a read-only listing 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?

A single front-loaded sentence states the operation, scope, and purpose with no filler. Every word contributes to the agent's understanding.

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 is simple, has no required parameters, and its read-only/idempotent nature is already captured by annotations; an output schema also exists to explain return values. The only notable gap is parameter meaning, which is partially mitigated by self-explanatory names and defaults.

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 never mentions path or full_output. The phrase 'under the local shared workspace' weakly implies the path parameter is relative to that workspace, but full_output is left completely unexplained, so the description fails to compensate for the missing schema descriptions.

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 uses a specific verb ('List') and resource ('files under the local shared workspace'), and explains the workspace's purpose ('used to move data between hosts'). This clearly differentiates it from siblings like shared_read/shared_write, which presumably read or write file contents, and hosts_list, which lists hosts.

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 provides clear context that this tool inspects the local shared workspace for inter-host data movement, so an agent can infer when to call it before transfers. It does not explicitly name alternatives or exclusions, but the context is strong enough to avoid obvious misuse.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds useful context beyond annotations: it specifies 'one' file (limiting scope) and 'UTF-8' encoding, which are behavioral traits not captured in the schema or annotations. This adds value without contradicting the structured hints.

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 with zero waste. It front-loads the action and scope, and every word contributes to meaning. It is appropriately sized for a simple read tool and is well-structured.

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?

Although an output schema exists (so return format is covered), the description leaves critical behavioral details unexplained. The two parameters are undocumented, full_output's effect is ambiguous, and there is no mention of error conditions or edge cases (e.g., missing file, non-UTF-8). For a tool with a required path and a boolean flag, the description is too minimal to guarantee correct invocation.

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%, so the description must explain parameters to compensate. It does not mention 'path' or 'full_output' at all. The description gives no meaning for these parameters: an agent cannot infer that path is a required file path or what full_output controls (likely verbosity or content output). This is a significant gap given two parameters, one of which is a boolean that could drastically alter behavior.

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 states a specific verb ('read'), a resource ('one UTF-8 file'), and a location ('local shared workspace'). It clearly distinguishes from siblings like shared_write (write) and shared_list (list files) by implying a single-file read, and the UTF-8 detail adds specificity. This is a clear, non-tautological purpose.

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 provides no guidance on when to use this tool over alternatives. It does not mention conditions like 'use this when you need file contents' or exclude cases like reading multiple files or directories. Among siblings like shared_write, shared_list, and host_exec, there is no routing help, leaving the agent to infer usage from the purpose alone.

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?

Annotations already convey idempotency and non-destructiveness, lowering the bar. The description adds the useful detail that the file is UTF-8 encoded, but it does not disclose whether existing files are overwritten, whether directories are created, or what edge cases exist. No contradiction with annotations is present.

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, front-loaded sentence with no filler words. It is appropriately concise, though it sacrifices needed parameter and behavior detail for brevity.

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 is relatively simple and has an output schema plus annotations, so the description does not need to explain return values. However, the absence of any explanation for the full_output parameter and the lack of path-related conventions leave an incomplete picture for fully correct invocation.

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%, so the description must compensate by explaining the path and content parameters. It does not mention path, content, or the full_output flag at all; the only semantic hint is that the file is UTF-8 encoded. This is insufficient for an agent to confidently interpret all three parameters.

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 ('Write'), the resource ('one UTF-8 file'), and the location ('local shared workspace'). It distinguishes itself from sibling read tools like shared_read and from host_* tools by emphasizing 'local', though it does not explicitly name any 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?

The description implies usage for writing files in the local shared workspace, which gives useful context among siblings. However, it provides no explicit guidance about when to prefer this tool over alternatives, and it does not mention exclusions or conditions such as path conventions or conflicts with host transfer tools.

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