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

With no annotations, the description must disclose behavioral traits, but it only states the basic action. It does not mention whether existing local files are overwritten, how authentication/credentials are handled, what transfer protocol is used (e.g., SFTP/SCP), or the meaning of the timeout and allow_sensitive parameters. The minimal description fails to convey important behavior.

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 short sentence with no wasted words, but it is under-specified. It lacks necessary context, so the brevity is not appropriately sized for a tool with multiple parameters and no annotations. It is concise but at the expense of completeness.

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?

Given no output schema, no annotations, and 5 parameters, the description should provide more context about return values, error handling, and parameter behavior. It only covers the basic purpose, leaving significant gaps in what the agent needs to use the tool correctly.

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. It does not explain any parameter (host, remote_path, local_path, timeout, allow_sensitive) beyond their names. The phrase 'download files' only implies remote_path and local_path, but it does not add semantic meaning to the parameters, especially allow_sensitive and timeout.

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 ('download') and the resource ('files from remote host to local'). It distinguishes itself from sibling tools like ssh_upload (reverse direction) and ssh_download_dir (directory variant), making its purpose 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention that ssh_download is for single files while ssh_download_dir is for directories, nor any prerequisites like SSH connectivity. The absence of any usage context leaves the agent without decision support.

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 provided, the description's single sentence carries the full burden of behavioral disclosure. It only states the core functionality and does not mention side effects (e.g., overwriting local files), prerequisites (SSH credentials), security considerations (allow_sensitive parameter), or error/timeout behavior. This lack of detail leaves significant behavioral ambiguity.

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, concise sentence with no unnecessary words. It front-loads the core function and is appropriately sized for a tool with a straightforward purpose, making it easy to parse quickly.

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?

Given the moderate complexity (5 parameters, 3 required), no annotations, and no output schema, the description should provide more context. It omits parameter details, usage scenarios, and behavioral side effects, leaving the description inadequate for fully autonomous tool 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%, and the description does not explain any of the five parameters beyond their names. While host, remote_dir, and local_dir are fairly self-explanatory, timeout and especially allow_sensitive are ambiguous and would benefit from clarification. The description fails to compensate for the low schema 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 clearly states the tool's action: '从远程主机下载目录到本地（递归下载所有文件）' (Download directory from remote host to local, recursively download all files). It specifies the verb (download), resource (directory), and scope (recursive), which distinguishes it from sibling tools like ssh_download (file download) and ssh_upload_dir (upload).

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 downloading directories recursively but does not explicitly state when to use this tool versus alternatives like ssh_download for files or ssh_upload_dir for uploading. No exclusions or preconditions are mentioned, so guidance is implied rather than explicit.

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 are provided, so the description carries the full burden. It only states the basic action and return, without disclosing critical behaviors such as command execution privileges, security risks, exit code handling, or side effects on the remote host. The existence of an 'allow_dangerous' flag in the schema is not mentioned.

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, straightforward sentence that is easy to parse and front-loads the core action. However, it is overly terse given the tool's complexity, bordering on under-specification rather than efficient conciseness.

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?

This is a remote shell execution tool with no output schema and no annotation support, yet the description provides no detail on authentication, security guards, timeout behavior, or return format. It is severely incomplete for an operation with significant security implications.

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 0%, and the description adds minimal meaning beyond the schema. It only hints at 'command' being a shell command, while host, shell, timeout, environment, and allow_dangerous parameters remain unexplained. The description does not compensate for 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 clearly states the action ('execute a shell command'), the resource ('on a remote host'), and the outcome ('return the result'). It distinguishes itself from sibling tools like ssh_exec_batch by specifying 'a single shell command' (一条 shell 命令).

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 phrasing 'a single shell command' implies use for individual commands vs. batch operations (ssh_exec_batch), but there is no explicit guidance on when to choose this over alternatives, nor any mention of prerequisites or exclusions.

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 must carry the full burden of behavioral disclosure. It only mentions '错误中断' (error interruption), which merely reflects the stop_on_error parameter in the schema. It does not disclose that the tool executes arbitrary remote commands, potential security implications, output behavior, or sequential execution, leaving significant transparency gaps.

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, concise sentence with no redundant words. It is efficiently front-loaded, stating the primary action and one key feature, and is appropriately sized for the tool's apparent simplicity.

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?

Given the absence of annotations and an output schema, the description is the only narrative source for understanding the tool. It fails to cover return values, authentication, error handling details, or execution semantics, leaving the agent without critical context for safely invoking this remote command execution tool with four parameters.

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. It adds no explanation for host, timeout, commands, or stop_on_error beyond what their names imply; '多条命令' and '错误中断' are just natural-language restatements of the schema properties, providing zero added meaning.

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 '批量执行多条命令，支持错误中断' (batch execute multiple commands with error interruption), clearly indicating the tool's action and scope. It does not explicitly contrast with the sibling ssh_exec, but 'batch' implies multiple commands, so it is clear but not fully differentiated.

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 executing multiple commands in one call, but it does not provide explicit guidance on when to use it versus the single-command ssh_exec or other alternatives. The 'batch' wording hints at the use case, but no exclusions or alternative tool references 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 provided, the description carries the full burden. It discloses the exact log file path (~/.ssh/mcp-ssh.log or SSH_LOG_FILE), the aggregation behavior, the returned fields (timestamp/host/username/tool/args/status/duration_ms), and output limits. This is detailed and transparent.

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 two sentences, front-loads the purpose, and every clause adds value—no filler. It efficiently covers file source, output format, filtering, and output limits.

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, has no annotations, and no output schema. The description provides return fields, file location, filters, and a size cap, making it quite complete. Minor gaps include not specifying the size cap value or behavior when since_minutes is 0, but for a log query tool this is sufficient.

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 0%, but the description compensates by mentioning filter support for host, tool, and since_minutes, and notes that output is constrained by limit. It does not explain exact filter semantics (e.g., exact vs. partial match) or the meaning of since_minutes=0, but it covers all parameters at a functional level.

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 '查询' (query) and resource '行为日志' (behavior logs), immediately distinguishing this tool from siblings like ssh_exec or ssh_scan. It also states it is read-only and intended for AI analysis, making the purpose unmistakable.

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 indicates the use case: querying recent behavior logs for AI analysis, and it is read-only, differentiating it from execution tools. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a 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?

With no annotations provided, the description carries the full burden. It states the operation ('get') but does not explicitly disclose side effects or permissions, though the verb 'get' implies read-only behavior. Minimal transparency is provided.

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, concise sentence that immediately conveys the tool's purpose with no filler or repetition.

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?

Given no output schema, the description does not explain what the response includes beyond generic 'status information.' It is sufficient for invoking the tool but vague about return format, which is a clear gap.

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 tool has zero parameters, so the description need not elaborate on parameter semantics. The baseline for zero-parameter tools is 4, and the description adds no irrelevant parameter details.

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 the specific verb '获取' (get) and identifies the resource '当前审核模式及状态信息' (current review mode and status information), clearly distinguishing it from sibling tools like ssh_set_review_mode which modifies the mode.

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 guidance is given about when to use this tool versus alternatives such as ssh_set_review_mode or ssh_get_audit_logs. There is no mention of prerequisites or exclusions.

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 are provided, so the description carries the full burden. It only states the basic action; it fails to disclose behaviors such as how connections are handled, whether hidden files are excluded by default, output format, or error handling. This is a minimal disclosure with no additional behavioral context.

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, clear sentence with no redundant wording. It is front-loaded and immediately conveys the tool's purpose. However, it is very brief, but that is more a completeness issue than a conciseness issue.

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 output schema and no annotations, the description should explain what the tool returns and any relevant behaviors. It only says it lists files and subdirectories, ignoring defaults like remote_path='~' and show_hidden=false, timeout handling, and return format. The tool has 4 parameters, making this description inadequate for reliable agent use.

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 does not compensate. None of the four parameters (host, timeout, remote_path, show_hidden) are explained beyond their names. The description only implies remote_path via 'specified directory', leaving host, timeout, and show_hidden undefined.

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 lists files and subdirectories in a specified remote directory. This distinguishes it from sibling tools like ssh_exec, ssh_upload, and ssh_download, which perform different operations.

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 versus alternatives such as ssh_exec (which could run ls) or ssh_stat_file. There are no usage scenarios, prerequisites, or exclusions mentioned.

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 must carry the behavioral disclosure. It mentions excluding wildcard entries and cross-platform adaptation, but does not explicitly state the tool is read-only or describe the output format. The nature of the operation is implicitly safe, but additional behavioral context would improve transparency.

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 concise sentence that efficiently conveys the core purpose and the key nuance about excluding wildcard entries. Every word earns its place, with no redundancy or 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?

Given the tool's simplicity (no parameters, no output schema), the description adequately covers its purpose and key behavior. It lacks specifics about the return value format and potential error cases, but for a straightforward list operation this is a minor gap.

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 tool has zero parameters, so the description cannot add parameter-level semantics. The baseline of 4 is appropriate because the absence of parameters is clear from the schema and there is nothing to document.

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 the specific verb 'list' and names the resource 'host aliases' from ~/.ssh/config, which clearly distinguishes it from sibling tools like ssh_exec or ssh_scan. It also adds a precise detail about excluding wildcard entries, making the tool's scope 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 the tool is for retrieving configured SSH hosts but does not explicitly state when to use it versus alternatives. No exclusions or when-not-to-use guidance is provided, though the context of sibling tools suggests it is a preliminary step for other operations.

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 provided, the description carries full responsibility for disclosing behavior. It only says 'create directory' and omits any details about parent creation (despite a 'parents' parameter), timeout behavior, error handling, or side effects. The agent gets no warning about mutation or remote side effects.

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 short sentence, which is concise but under-specified for a tool with four parameters. It is front-loaded and easy to read, but it lacks the structural detail needed for a tool with options like 'parents' and 'timeout'.

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 and no annotations, and the description provides only the most basic action. Missing information includes return values, the effect of the 'parents' flag, timeout semantics, and whether the operation is reversible or requires specific privileges. The tool is effectively a stub description.

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. It does not explain any parameter meanings, including remote_path, parents, timeout, or host. The description adds no value beyond the schema field names, leaving the agent to guess what 'parents' or 'timeout' control.

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 the tool creates a directory on a remote host, which is a specific verb+resource. It clearly distinguishes from siblings like ssh_exec or ssh_remove, though it does not explicitly name alternatives. The purpose is unambiguous despite the lack of additional context.

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 versus alternatives. It does not mention any prerequisites, exclusions, or scenarios where another sibling tool would be more appropriate. This is a pure purpose statement without usage 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?

No annotations are provided, so the description carries full responsibility for disclosing behavior. It only mentions deletion of files/directories but does not clarify permanence, recursive behavior, permission requirements, or whether deletion is irreversible. Given the absence of annotations, this is insufficient.

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 concise sentence that is front-loaded with the core action and resource. It contains no redundant or filler words, effectively earning 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?

With no annotations, no output schema, and minimal description, key behavioral context is missing. The tool involves potentially destructive operations over SSH, yet the description does not mention recursive flags, safety warnings, or error conditions. This is incomplete for a delete 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 coverage is 0%, and the description adds no parameter-level meaning. It does not explain the role of 'recursive' (critical for directory deletion), 'timeout', or 'remote_path'. The agent must rely entirely on the raw schema, which lacks descriptions, so the description fails to compensate.

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 '删除远程主机上的文件或目录' (delete files or directories on remote host), which clearly identifies the action (delete) and resource (remote files/directories). This distinguishes it from sibling tools like ssh_upload, ssh_download, and ssh_exec, which perform different operations.

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 versus alternatives, nor does it mention prerequisites, exclusions, or examples. It only states the basic function without context, leaving the agent to infer when this tool is appropriate.

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 are provided, so the description must carry the full burden of behavioral disclosure. It only states the basic scanning behavior, omitting potential side effects (e.g., network load), permissions required, whether it is read-only, or what the output format looks like. This is a significant gap for a tool that actively probes network hosts.

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 stating the core action and default behavior. It is concise, contains no redundant words, and efficiently 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?

Given that the tool has 5 parameters, no annotations, and no output schema, the one-line description is insufficient. It lacks details on parameter semantics, expected output, and operational caveats. This is a complex scanning tool that requires more thorough documentation for an AI agent to use it correctly.

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 schema has zero description coverage for its 5 parameters, so the description must compensate. It only hints at 'port' (default 22) and 'network' (LAN segment), while entirely ignoring 'detail', 'timeout', and 'max_workers'. This provides only partial meaning for a subset of 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 uses a specific verb '扫描' (scan) and resource '局域网网段' (LAN network segment), with a clear objective to discover online hosts with a specified open port (default SSH 22). This clearly distinguishes it from sibling tools like ssh_exec or ssh_list_hosts, which are direct SSH operations.

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 by stating the tool scans a network to discover SSH-accessible hosts, but it does not explicitly mention when to use it versus alternatives or any exclusions. No guidance is provided on when this should be preferred over other SSH tools.

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 are present, so the description must disclose behavioral traits. It only says 'switch review mode' without explaining side effects, permission requirements, or whether the change is reversible. The meaning of each mode (off, whitelist, manual, smart) is not elaborated, leaving the agent without critical behavioral context.

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, concise sentence that front-loads the action and option list. Every word earns its place; there is no wasted or irrelevant content.

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?

While the tool is simple (one enum parameter), the description omits necessary context about what each mode does and when to use it. Without an output schema, the agent still needs a basic understanding of the modes' effects to invoke the tool correctly. The one-line description is insufficient for choosing the right mode.

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 schema already defines the 'mode' parameter with an enum of the exact same values, so the description adds no semantic meaning. It merely repeats the enum list, and the phrase '可选' could be misinterpreted as 'optional' despite the parameter being required. This is a redundant and slightly misleading description of 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?

The description clearly states the tool's function with a specific verb ('switch') and resource ('review mode'), and lists the allowed options. This distinguishes it from siblings like ssh_get_review_mode, which is a read operation.

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 guidance is provided on when to use this tool versus alternatives. It does not mention that ssh_get_review_mode is for reading the current mode, nor does it explain any prerequisites or context for setting a particular mode.

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 full responsibility for behavioral disclosure. It only says 'get detailed information' without explaining behavior on missing files, symlink handling, permission requirements, or return format. This is a significant gap for a stat-like 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?

The description is a single concise sentence with no filler. It front-loads the verb and resource, making it immediately scannable. Perfectly sized for a simple tool.

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?

Given the lack of annotations and output schema, the description should provide more context about what 'detailed information' entails, error handling, and invocation prerequisites. The current description is too thin to fully guide an agent, despite the tool's low complexity.

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. It does not explain 'host', 'timeout', or 'remote_path' beyond the schema property names. The phrase 'file or directory' hints that remote_path is the path, but the description adds little semantic value over the bare 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?

The description clearly states the tool's function: '获取远程文件或目录的详细信息' (get detailed information of remote file or directory). It uses a specific verb ('get') and resource ('remote file or directory'), and distinguishes from siblings like ssh_list_dir (list contents) and ssh_remove (delete).

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 guidance is provided on when to use this tool versus alternatives. It does not mention use cases like checking existence or permissions, nor does it name sibling tools for contrast. The agent must infer usage from the name 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?

There are no annotations to cover safety or side effects, so the description carries the full burden. It only states the action without explaining overwrite behavior, what happens on failure, whether the remote directory is created, or if any permissions are required. This lack of behavioral context is a significant gap.

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 concise sentence, which is efficient in readability. However, it is under-specified; it lacks any structure such as parameter explanations or usage notes, making it minimal but not appropriately informative for a tool with five parameters.

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?

Given the tool's complexity (5 params, no annotations, no output schema), the description is incomplete. It omits crucial operational context like authentication requirements, network dependencies, return values, and interactions with sibling tools. This is insufficient for safe and 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%, and the description adds no meaning to the parameters. It does not mention how host is specified, what timeout or overwrite do, or the format of local_path and remote_path. The description fails to compensate for the schema's lack of semantic detail.

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 'Upload local file to remote host' clearly states the verb (upload) and resource (local file to remote host), which is specific enough to understand the core action. However, it does not explicitly distinguish this tool from the sibling ssh_upload_dir, leaving the agent to infer that this tool is for files only.

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 guidance is provided about when to use this tool versus alternatives. The description does not mention exclusions (e.g., directories should use ssh_upload_dir) or prerequisites such as SSH access or host configuration. The agent is left without context for selection.

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 recursion, but omits critical behaviors such as the overwrite flag defaulting to false, whether remote directories are created if absent, permission requirements, or error handling. This is insufficient for a mutation 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?

The description is a single, front-loaded sentence that communicates the core action and recursion without fluff. It is concise and aptly sized for the basic intent, though it omits detail that would make it more helpful.

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?

Given the tool has 5 parameters, no annotations, and no output schema, the description is too minimal. It does not explain timeout semantics, overwrite behavior, path conventions, or what happens on conflict. The recursive note is useful but leaves significant gaps for 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%, and the description does not compensate. It implicitly covers local_dir and remote_dir, but leaves timeout and overwrite unexplained. The agent must rely on parameter names alone, which is risky for nuanced parameters like overwrite.

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 uploads a local directory to a remote host and explicitly notes recursive upload of all files. This specific verb+resource combination distinguishes it from sibling tools like ssh_upload (single file) and ssh_download_dir.

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 guidance is given on when to use this tool versus alternatives. It does not mention that ssh_upload is for single files, nor provide conditions like 'use this for directory trees' or exclusions. The usage context is only implied by the description.

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