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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool may open or reuse a connection, but it does not clarify whether this mutates any persistent state, whether it requires an existing connection, or what happens on failure. The phrase 'report basic identity' is vague without further detail.

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, well-structured sentence that front-loads the main action and purpose. Every word earns its place, 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?

An output schema exists, so return format is covered; however, the description omits important context like when the tool should be used, any side effects of opening a connection, and whether a prior list_hosts call is required. For a simple one-parameter tool this is acceptable but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; the host parameter is already described as 'Configured host name from list_hosts'. The description adds 'to a host', which merely restates the parameter's role without adding new meaning. Baseline 3 is appropriate when the schema carries the semantic weight.

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 uses a specific verb ('Open (or reuse)') and a clear resource ('the SSH connection to a host'), then states the action of reporting basic identity. This distinguishes it from sibling tools like run_command or list_hosts, 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?

No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites such as calling list_hosts first, nor does it explain situations where check_connection is preferred over other connection-related 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?

没有注释信息，描述承担了全部行为揭示的负担。但描述仅提及'关闭'，未提供对副作用、可逆性、影响范围（是对所有主机还是当前会话中的主机）的说明，也没有讨论权限要求或结果的回执。对于执行级别的操作，这样的描写过于简略。

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?

用一句话完成了完整的表述，直接而精确，没有冗余。既包含了动词和范围，又无需额外解释，结构上非常精炼。

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?

工具本身简单，且标记有输出schema，虽然描述没有一一列举返回值，但输入参数也均已覆盖，所以基本完整。缺少权限或错误状况的披露，但因为无任何注释，仍需一点补充才足够。

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?

参数模式（host）的覆盖率为100%，描述了'配置的主机名，或all'，与参数定义完全一致。描述没有添加额外的语义，但参数本身已清晰，因此按基准保留3分。

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?

描述明确了动词（关闭）和资源（SSH连接），并包含了'或所有'的范围，与其他兄弟工具（如list_hosts、check_connection）明显不同。虽然未明确提及其他工具，但基于动词和资源，意图足够清晰。

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?

描述没有提供何时使用此工具与替代工具，也没有明确排除其他情况。仅声明执行什么，未指明前置条件（如主机必须已配置）或哪些场景不适合，例如需要先检查连接。

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 behavioral burden. It states that the tool lists a remote directory with sizes and permissions, implying a read-only operation, but it does not explicitly say whether the operation is safe (no mutation), whether deeper directories are recursed, or whether hidden files are included. Since it's a low-risk list operation, the description is minimally adequate but lacks depth.

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, complete sentence with no filler. It front-loads the action and the specific focus (sizes and permissions). Every word adds value, making it highly concise and 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?

While the tool is simple and an output schema exists (so return format is covered), the description fails to explain when to use this tool versus siblings like list_hosts (list configured hosts) or read_file. The lack of any usage context leaves an agent uncertain about the appropriate invocation scenario. This is a notable gap for a seemingly straightforward 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?

The schema description coverage is 100%—both host and path are documented with meanings. The description adds no extra parameter details, just restates the tool's function. Following the baseline rule for high schema coverage, a score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('list'), a specific resource ('remote directory'), and notable output attributes ('sizes and permissions'). This distinguishes it from sibling tools like read_file (reading file contents) and run_command (executing commands), so an agent can identify its purpose without opening the schema.

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 that list_directory is for directory listings while read_file is for file contents, nor does it offer any condition or exclusion. The agent must infer usage purely from the name and description, which is insufficient.

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, so the description carries the full burden. It does not disclose whether this operation is purely read-only (no side effects), whether it reflects dynamic state or static config, or whether it may be slow due to connectivity checks. The verb 'list' implies read-only, but key behavioral details are 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?

A single, front-loaded sentence contains the essential information with no fluff. It earns its place and is easy to scan.

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 low complexity (0 params) and an output schema present, the description is minimally adequate. However, it leaves ambiguity about what 'configured host' means in the context of this host-management toolset—for example, whether hosts are filtered by reachability or whether it reads from cache. This matters for selecting the right tool among siblings like reload_hosts and check_connection.

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 there is no parameter behavior to document. Baseline for 0 params is 4, and the description does not need to add anything about schema specifics. No gaps here.

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 exact action ('List'), the resource ('every configured host'), and the specific fields returned ('access mode and description'). It is unambiguous and easily distinguished from sibling tools like reload_hosts or list_directory.

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 reload_hosts or check_connection. The description does not mention whether this list is read from static configuration or if it queries live hosts, which would influence tool 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 provided, the description carries the full burden of behavioral disclosure. It only states the action without mentioning limits like max_bytes, return format, error behavior, or whether it reads the entire file. The description does not contradict any annotations since none exist.

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 no filler, making it highly concise. It is appropriately sized for a simple tool, though it sacrifices behavioral details 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?

For a simple read operation, the description conveys the core action, but it lacks context for choosing this tool over tail_log and does not mention the max_bytes truncation behavior. However, the presence of an output schema and detailed parameter schema reduces the need for further elaboration. Overall, it is minimally complete for a straightforward 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?

The input schema already provides 100% coverage with descriptions for all three parameters (host, path, max_bytes). The description adds no additional semantic information about these parameters, so the schema itself bears the responsibility. Baseline 3 applies due to high 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 uses a specific verb 'read' and a resource 'remote file' over SFTP, clearly indicating the operation. It differentiates from write_file and list_directory, though it is less explicit about the difference from tail_log. Overall, the purpose is clear and 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 provides no guidance on when to use this tool versus alternatives like tail_log or list_directory. There are no explicit conditions, exclusions, or cross-references to sibling tools. An agent must infer usage solely from the name and one-line description.

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 burden of behavior. It discloses the potentially disruptive 'drop all open connections' side effect, which is valuable. However, it omits details about whether this is safe, reversible, or what happens to running commands, leaving some uncertainty for an agent.

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 concise sentence that effectively communicates both the primary action and the key consequence. No wasted words, information is front-loaded.

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 simplicity of the tool (no parameters), the description is reasonably complete. It explains what is reloaded and the consequence of dropping connections. The output schema exists, so return value details are not necessary. Minor gaps remain about prerequisites or post-conditions, but not critical.

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, and the schema confirms this. The description adds meaning about the operation's effect without needing to explain parameter semantics. Baseline 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (reload), the resource (inventory file), and the side effect (drop all open connections). This differentiates it from sibling tools like list_hosts and check_connection, which have different 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 versus alternatives. It implied that it loads hosts from disk, but does not mention scenarios such as after editing the inventory file or troubleshooting stale connections, nor does it distinguish from list_hosts or connect/disconnect 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly explains that read-only hosts refuse modification commands before execution, which is valuable behavioral context. However, it does not mention other aspects like output format, error handling, or shell environment, leaving some 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 two sentences, front-loading the main function and then adding the crucial access-policy constraint. 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 rich schema and presence of an output schema, the description need not detail return values. It covers the essential behavioral constraint (access policy) and the basic operation. It does not discuss command execution details like default shell or environment, but for this tool that 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?

Schema description coverage is 100%, so all four parameters (host, command, timeout, working_dir) already have descriptions. The tool description adds no extra parameter meaning beyond what the schema provides, matching the baseline of 3.

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 clear verb ('Run') and resource ('a shell command on a host'), making the core function obvious. It is easily distinguished from sibling tools like read_file or service_status, but it does not explicitly name any sibling or contrast itself, so it falls short of a 5.

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 does not specify when to use this tool versus alternatives. It mentions host access policy but does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference any sibling tool. The usage context is only implied by the general nature of running commands.

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 of disclosing behavioral traits. While the verbs such as 'start' and 'stop' imply mutation, the description never mentions potential side effects, permission requirements, or that it may require administrative privileges. This is a meaningful gap for a tool that changes system state.

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 that enumerates all possible actions and the target resource. There is no redundant language or verbose phrasing, making it appropriately sized for a tool with a narrow scope.

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 tool with only three fully described parameters and an output schema present, the description adequately communicates what the tool does. It lacks explicit usage guidance, but given the simplicity of the action set, it is otherwise complete enough for an agent to call 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 input schema provides a name and a description for all three parameters (host, unit, and action), yielding 100% schema coverage. The description adds little beyond restating the allowed action values, so it does not materially enhance understanding of parameter usage.

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 lists specific verbs (start, stop, restart, reload, enable, disable) and the resource (systemd unit), making the primary action obvious. However, it does not explicitly contrast itself with the sibling tool service_status, so it falls short of fully distinguishing between similar 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 offers no guidance on when this tool should be used relative to alternatives like service_status (which presumably reads state) or run_command. It does not state any contextual conditions, exclusions, or recommended alternatives, leaving the agent to infer when to choose this over other 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?

With no annotations, the description carries the full burden of behavioral disclosure. 'Show' correctly implies a non-mutating read-only operation, which is the key safety trait. However, it does not disclose that the tool operates on a remote configured host, nor any possible prerequisites like reachability or credentials, nor error behavior when the unit is absent.

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 every word contributing meaning. It is clear, concise, and places the verb and object at the front, making it immediately scannable.

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 read-only status tool, the description and schema cover the essentials: the parameters are well-documented and an output schema exists to define return values. However, the definition provides no context about remote execution, host configuration prerequisites, or how this tool relates to siblings in the suite, leaving an agent with only the training context to fill these 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 coverage for parameters is 100%, and the schema already provides meaningful descriptions ('Configured host name' and 'systemd unit name, e.g. nginx'). The tool description adds no additional meaning or context beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Show' and a specific resource 'status of a systemd unit', clearly stating what the tool does. It does not explicitly differentiate it from siblings like system_overview or service_control, but the static 'status' wording makes the core purpose evident.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention that service_control should be used for modifications, nor does it clarify when system_overview might be more appropriate. An agent receives no contextual cues for tool selection beyond the name and schema.

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 convey all behavioral traits. It only lists what is collected and gives no hint about potential side effects, required privileges, network behavior, or whether it performs read-only actions. The word 'collect' implies a read operation, but this is not explicit, nor does it warn about possible latency, error conditions, or how the tool accesses the remote host.

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, efficiently structured sentence. It front-loads the verb and object, then uses a colon to introduce a compact list of components. Every word contributes meaning, and there is no redundant phrasing or verbose elaboration.

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 tool with one parameter and an existing output schema, the description provides the essential scope of what is collected. However, it lacks usage context and any indication of behavioral constraints such as whether the host must be online or whether the tool requires special permissions. Given the simplicity and the presence of an output schema, the description is minimally complete but leaves some context to be inferred.

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 input schema already provides a description for 'host' ('Configured host name'), achieving 100% schema description coverage. The tool description simply names the operation without adding any extra semantic detail about the parameter, such as accepted formats, defaults, or relationship to host configuration. With full schema coverage, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb, 'Collect', and a clear resource, 'health snapshot', then enumerates the concrete components (load, memory, disk, top processes, failed units). This clearly distinguishes it from sibling tools like service_status, which targets only services, or run_command, which executes arbitrary commands. An agent can immediately understand that this tool provides a broad system-level overview.

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 its alternatives. It does not mention that service_status should be used for deeper service details, or that check_connection is for basic connectivity. There is no context about suitable scenarios, preconditions, or exclusions, leaving the agent to infer usage solely from the tool's name and description.

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 of behavioral disclosure. It does not clarify whether the tail follows continuously or returns a fixed number of lines (though 'lines' implies a static return), nor does it mention permissions or potential blocking behavior. This is a significant gap for a tool that could exhibit real-time 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 concise at one sentence, but it is also minimal to the point of omitting important context. It earns a middle score for being succinct yet under-specified.

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 (dual source types, potential real-time behavior) and minimal description, the definition is incomplete. There is no mention of use cases, prerequisites (such as configured hosts), or how it relates to sibling tools. The presence of an output schema does not compensate for the lack of contextual guidance.

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 the schema already documents all parameters well. The description adds no additional meaning beyond the schema, 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?

The description clearly identifies the operation ('Tail') and the resource ('a log file or a systemd unit's journal'), which distinguishes it from siblings like read_file or run_command. It is specific and actionable.

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. The description does not mention scenarios (e.g., real-time monitoring vs. static reads) or compare to read_file or service_status, leaving the agent to infer appropriate usage.

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 burden. It discloses the destructive nature ('Overwrite') and the read-only refusal, which is useful context. However, it does not mention the backup behavior (present in the schema but not disclosed in text), the possibility of partial failure, or requirements like host connectivity. It partially covers behavioral transparency but not fully.

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, front-loaded with the primary purpose. Every word earns its place: the first sentence defines the action and the second provides a key preventive constraint. No fluff 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?

The description is complete enough for a straightforward overwrite tool. The output schema exists to clarify return values, and the schema covers the parameters. The read-only refusal ensures agents do not misuse it on restricted hosts. It lacks a bit of behavioral context but is sufficient overall.

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 the schema already fully explains every parameter (host, path, backup, content). The description adds no extra semantic value beyond what the schema documents, 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?

The description states a specific verb ('Overwrite') and resource ('a remote file'), which clearly distinguishes it from read-only siblings like read_file or list_directory. The intent is unambiguous and leaves no room for confusion about what the tool does.

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. While it mentions the read-only host refusal, that is a constraint rather than usage context. There is no mention of using read_file to inspect the file before overwriting, or any explicit selector for when to choose write_file over run_command.

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