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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions bootstrap password usage, credential saving behavior (conversion to key-based), and trust_unknown_host details. However, it doesn't describe what happens on failure or session management beyond connection, so 4.

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, which is concise, but it lacks structure for the 12-parameter complexity. Important behavioral details (like credential saving) are not front-loaded. A longer description with structured details would be more helpful, so 3.

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 complexity (12 params, nested objects, no output schema), the description is incomplete. It doesn't explain return values or connection lifetime. Annotations are absent. The description covers purpose and some behavior but misses key context about success/failure indicators.

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 baseline is 3. The description adds value by explaining the purpose of password (first-time bootstrap) and save_credentials behavior (conversion to key-based), which goes beyond schema. Nested jump_host adds complexity, but the description references it indirectly. Score 4.

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 ('Connect') and the resource ('remote Ubuntu server via SSH'), with the verb+resource pattern. It distinguishes from siblings like ssh_execute or ssh_download_file but doesn't explicitly differentiate from ssh_connect_saved, so 4.

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 like ssh_connect_saved or ssh_setup_key_auth. The presence of many sibling tools suggests a need for usage context, yet the description only states the basic purpose. A 3 reflects the minimal viable 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?

No annotations are provided, so the description must convey behavioral traits. It describes the action (connect) and input (saved credential name), but does not disclose what happens if credentials are invalid, whether a new connection is created or reused, or any side effects. Adequate but missing details.

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 directly states the purpose. It is concise and front-loaded, but omits necessary behavioral and usage details that could be added without making it verbose.

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 2 parameters, no output schema, and no annotations, the description is serviceable but lacks information on return behavior, connection state changes, and error conditions. It is minimally complete for a straightforward connection tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema: it mentions 'saved credential name' but the schema already describes 'name' as such. No additional context for 'connection_name' is provided.

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 specifies the verb 'connect' and the resource 'remote server using a saved local SSH credential name', distinguishing it from sibling tools like ssh_connect (likely prompts for credentials) and ssh_save_credentials. It clearly indicates the tool uses saved 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 tool description implies it should be used when a saved credential exists, but it does not explicitly state when to use this tool over ssh_connect or provide guidance on prerequisites like having saved credentials. No alternative tools are 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?

No annotations are provided, so the description carries the full burden. It correctly indicates a destructive action ('Delete'), but does not clarify side effects (e.g., whether deletions are irreversible or affect active connections). This is adequate but not thorough.

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 directly states the tool's purpose with no unnecessary words 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 has one parameter, no output schema, and no annotations, the description is minimally sufficient. However, it lacks information about return values or error handling, which would be expected for a deletion tool.

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

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

Schema description coverage is 100%, so the parameter is well-documented in the schema. The description adds no extra meaning beyond 'delete by name', but the schema already provides sufficient detail. A score of 4 reflects that the description meets the baseline expectation.

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 'Delete a saved local SSH credential entry' uses a specific verb (Delete) and resource (saved local SSH credential entry), clearly distinguishing it from sibling tools like ssh_save_credentials or ssh_list_saved_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 does not provide guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or caveats (e.g., the credential must exist before deletion).

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 burden. It states the action (disconnect) but does not disclose any side effects or prerequisites beyond connection existence.

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 unnecessary words. It effectively conveys the tool's purpose.

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 (1 required param, no output schema), the description is complete enough. It lacks details like whether it closes all sessions or just one, but likely adequate.

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

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

Schema coverage is 100%, and the description adds no additional meaning beyond the schema. However, the single parameter is clearly described in schema, so baseline 3 is appropriate plus extra clarity from schema description.

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 'Disconnect' and the resource 'remote SSH connection', clearly indicating its action and differentiating it from sibling tools like ssh_connect or ssh_execute.

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 after establishing an SSH connection, but does not provide explicit guidance on when not to use it or mention alternatives among siblings.

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 phrase 'to an allowed local root' hints at a security restriction on local paths, but does not explain what happens if path is not allowed, or disclose other behaviors like overwrite policy, error handling, or authorization requirements. Since no annotations are provided, the description carries full burden, yet it omits important behavioral details.

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?

Single sentence, direct, no filler. Every word adds meaning—action, resource, protocol, constraint. Ideal length.

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 parameter count and no output schema, the description is reasonably complete for a file download tool. However, missing details on allowed local roots, file size limits, overwrite behavior, and how the connection_name relates to established connections (e.g., must be connected?) leave room for ambiguity.

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?

All three parameters are documented in the schema with descriptions (100% coverage), so the tool's description repeats no parameter info. However, it adds context about path restrictions ('allowed local root') that the schema does not capture, adding value beyond the schema.

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

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

Clearly indicates the action ('download'), resource ('remote file'), and mechanism ('via SFTP') with a constraint ('to an allowed local root'). Differentiates from sibling 'ssh_upload_file' but could explicitly contrast from 'ssh_execute'.

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 files, but does not specify when to prefer this over alternatives like 'ssh_execute' with scp, or mention prerequisites (e.g., connection must be established). No explicit when-not or exclusion conditions.

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 doesn't disclose behavioral traits like whether the command runs in a new shell, environment variables, or changes to remote state. The timeout parameter is mentioned in schema but not in description. Score 3 is appropriate as basic functionality is clear 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, concise sentence that conveys core purpose. No extraneous information. Could be slightly more detailed without being verbose, but as is, it 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 tool is relatively simple with three parameters and no output schema. The description provides minimal context. Given the presence of many sibling tools, additional context about assuming an active connection or return behavior would improve completeness. Score 3 as adequate but not rich.

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 three parameters. The description does not add any additional meaning beyond what the schema provides, such as how connection_name is resolved or what constitutes a valid command. Baseline 3 is correct.

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) and resource (command on remote SSH connection), providing a specific verb+resource pair. It distinguishes from siblings like ssh_connect (connection setup) and ssh_download_file (file transfer), but could be more explicit about the exact scope (single command execution vs. scripting).

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 use after establishing a connection via ssh_connect or similar, but does not explicitly state prerequisites or when to use alternatives like ssh_download_file. No guidance on when not to use this tool is provided.

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 disclose behavioral traits. It fails to mention what 'health' means, potential side effects (read-only?), required permissions, or whether it impacts SSH connections. The description is vague about its behavior beyond a simple health check.

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 one short sentence. It is concise but too brief, lacking adequate context. It does not earn its place with sufficient detail, so it is not an optimal use of space.

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 and no annotations, the description fails to explain what the tool returns or how health is assessed. For a tool with a simple parameter schema, the description should provide more context on the health check process, but it does not.

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

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

Schema coverage is 100%, so the description adds only general context. The input schema already describes the optional parameter and its behavior (checks all if not provided). The description adds no extra semantics, so baseline 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 clearly states the tool checks health of SSH connections. It specifies the verb 'check' and resource 'health of SSH connections'. However, it lacks differentiation from sibling tools; 'ssh_connect' and 'ssh_execute' might also imply health checks, so purpose is clear but not distinct.

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 'check the health', but it provides no explicit guidance on when to use this tool versus alternatives like ssh_connect or ssh_list_connections. It does not mention when not to use it or any prerequisites.

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 implies a read-only operation, but no annotations are provided to confirm safety. It doesn't disclose if the connections are to local or remote hosts, or if authentication is needed. With no annotations, the description should be more transparent. However, it is straightforward.

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?

Very concise at 5 words, but it lacks any additional context or structure. Could benefit from a sentence about the return format. Still, it is not verbose.

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 parameters and no output schema, the description is minimally adequate. However, it could mention what information is returned (e.g., host, port, user). The tool is simple, so a 3 is reasonable.

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?

Input schema has no parameters, and schema description coverage is 100%. The description correctly indicates no parameters needed, so no additional semantics are necessary.

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 it lists active SSH connections, distinguishing it from sibling tools like ssh_connect, ssh_disconnect, or ssh_list_saved_credentials. It could be more specific about the format or contents of the list, but it is clear enough for an agent.

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 on when to use this tool versus alternatives. For example, it doesn't mention when to use ssh_list_saved_credentials instead. The agent must infer from names alone, which may be ambiguous.

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 burden. It correctly indicates a read-only, non-destructive operation by saying 'list,' which is consistent with the tool name.

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 one efficient sentence that clearly states the action and resource without any 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?

Given zero parameters and a simple list operation, the description is complete enough. It doesn't mention return format, but with no output schema, that's acceptable for a list 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 has 100% description coverage (no properties), so the schema conveys everything. The description doesn't add parameter details because there are none.

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 clearly identifies the resource as 'saved local SSH credential entries,' which is distinct from other sibling tools like ssh_connect, ssh_save_credentials, or ssh_delete_saved_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?

It's clear when to use this tool: when you need to see saved SSH credentials. However, it doesn't explicitly exclude any contexts or mention alternatives like ssh_list_connections.

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 burden. It discloses critical behavior: when a password is provided, the server is contacted to bootstrap a key and only the key is saved. This adds important context beyond the schema about the side effect and stored credential format.

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 sentences, perfectly sized. First sentence states the core purpose. Second sentence adds a crucial behavioral detail. No filler words.

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 complexity (9 parameters, nested object, no output schema), the description is complete enough. It explains the key behavioral nuance. However, it could mention that the saved credential can later be used with ssh_connect_saved, enhancing integration awareness.

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 baseline is 3. The description adds a high-level behavioral note but does not add semantic detail for individual parameters beyond what the schema's descriptions already provide.

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 (save SSH credentials locally), the result (under a reusable name), and the key behavioral nuance (if password provided, bootstrap a key and save only the key credential). This distinguishes it from siblings like ssh_connect_saved or ssh_setup_key_auth.

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: when you want to store credentials for later reuse. However, it does not explicitly state when NOT to use it (e.g., if you only need a one-time connection, use ssh_connect) or mention alternatives like ssh_setup_key_auth for key-only setup.

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 explains the tool's actions (keypair generation, public key installation, credential saving), which are inherently destructive (overwriting keys/credentials) and involve network changes. However, it does not mention error conditions, idempotency, or what happens if the key already exists or the connection fails.

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, well-structured sentence that efficiently conveys the three-step process. Every part is essential, and no words are wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (multiple steps, side effects) and the absence of an output schema or annotations, the description provides a clear overview of what the tool does. However, it could be more complete by noting that the tool modifies the remote server's authorized_keys and saves a local credential, which are irreversible actions.

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?

Although the input schema already has 100% coverage with descriptions, the tool description adds context by explaining that 'key_name' defaults to credential_name or connection_name, and 'overwrite_saved_credential' controls overwriting existing credentials. This adds meaning beyond the schema's raw 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 clearly states a three-step process: generating a keypair, installing the public key on a remote server, and saving a credential for future use. It uses specific verbs (generate, install, save) and identifies the resources (local SSH keypair, remote server, credential), distinguishing it from siblings like ssh_connect or ssh_save_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 that this tool is used for setting up key-based authentication after password authentication, as the required 'connection_name' parameter refers to an 'Existing active SSH connection that authenticated with a password'. However, it does not explicitly state when not to use it or mention alternatives among siblings for similar 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?

With no annotations, the description must convey behavioral traits. It indicates the upload is via SFTP and requires an 'allowed local root', hinting at a security constraint. However, it doesn't disclose whether the file is overwritten, whether permissions are set, or what happens on failure. The behavior is partially 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 a single sentence that efficiently conveys the core purpose. It is front-loaded with the action and key concepts. No unnecessary words, but it could be slightly more informative within the same space.

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 3 parameters, 100% schema coverage, no output schema, and no annotations, the description could provide more context about behavior (e.g., overwrite policy, permission settings). It is adequate but not rich for a file transfer operation.

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?

Input schema covers all 3 parameters with descriptions. The tool description adds the context of 'allowed local root' for local_path, which provides additional meaning beyond the schema. However, for connection_name and remote_path, the description doesn't add extra value beyond the schema's own 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 clearly states the action (upload), the resource (local file), and the transport method (SFTP via an SSH connection). It distinguishes itself from sibling tools like ssh_download_file (which does the opposite) and ssh_execute (which runs commands). However, it doesn't explicitly mention that the upload is to a remote server, which is already implied by SFTP.

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 mentions 'allowed local root', giving a hint about prerequisites, but it doesn't clearly state when to use this tool vs alternatives like setting up key auth first or ensuring the connection is established. No explicit when-not or alternatives are provided.

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