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

No annotations are provided, so the description carries the full behavioral burden. It is a mutating tool that writes config into nine different IDEs, yet the description never says whether existing entries are overwritten, backed up, or reversible, whether elevated permissions are needed, or what happens on partial failure. dryRun is only explained by the schema, not by the description.

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 sentence, front-loaded with the verb and the primary target, with the IDE list as trailing detail. No waste, though the parenthetical aside slightly delays the concrete 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 mutating, multi-target config tool with no annotations and no output schema, the description covers what and where but not the safety profile an agent needs (overwrite/rollback behavior, permissions, side effects). Adequate but with meaningful gaps.

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

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

Schema description coverage is 100% and includes an enum and per-parameter descriptions, so the schema does the heavy lifting (baseline 3). The description adds no format or interaction detail beyond naming target IDEs in its scope sentence.

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

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

States a specific verb pair (detect and install/configure) and a concrete resource (ssh-remote-mcp or any MCP server) and enumerates the target IDEs. This clearly separates it from the ssh_*/sftp_* siblings, which operate on remote hosts, not local IDE configuration. It stops short of describing what configuration changes are actually made, so 5 is not warranted.

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?

Use is implied by the description (run this to wire an MCP server into local IDEs) but there is no explicit when-to-use, when-not, or alternative named. With 11 sibling tools in a different domain, some guidance on prerequisites (e.g. is a running ssh host needed first?) would help.

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 behavioral context. It discloses that results include structured file metadata, which is useful, but it omits auth requirements, default connection behavior when target is omitted, and any handling of symlinks, hidden files, or errors.

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 with no wasted words. The metadata list is compact and directly relevant to the tool's output.

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 schema fully documents the two parameters and the description names the returned metadata fields, which is helpful given there is no output schema. Still, the description lacks usage guidance and key operational context, leaving it only minimally complete for an SFTP listing 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 nested target object and dirPath are already well documented. The description adds no parameter-level meaning beyond the schema, making the baseline score of 3 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?

States a specific verb and resource: 'List remote directory entries.' It also names the returned metadata fields (type, permissions, owner, size, modified date), which helps distinguish it from file-reading siblings. However, it does not explicitly contrast itself with alternatives such as sftp_read_file.

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 when-to-use or when-not-to-use guidance. It does not mention alternatives like sftp_read_file for file contents, nor does it describe prerequisites or selection 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?

With no annotations, the description carries the full burden. It does disclose two real behavioral traits — the line-range slicing model and SHA-256 integrity verification ('safely') — which are not in the schema. However it omits truncation behavior when maxBytes is hit, encoding assumptions, and error semantics for missing files or auth failure, leaving material gaps for a read 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?

One sentence, front-loaded with the core action, with the differentiating features attached rather than buried. No filler or redundancy.

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

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

No output schema exists, so the description should at least sketch the return shape; it only implies a checksum is returned. For a 5-param tool with a nested connection target, the absence of any return-value or error-handling detail leaves a moderate gap, though the schema itself is fully described.

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 host/port/profile/privateKeyPath/filePath/startLine/endLine/maxBytes are already documented. The description only restates startLine/endLine in parentheses and adds no syntax, ordering, or interaction rules (e.g., how maxBytes interacts with endLine). 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?

States a specific verb and resource ('read remote file') plus its distinctive features (line-range slicing, SHA-256 checksum). It clearly separates itself from write-oriented siblings like sftp_write_safe and sftp_list_dir, though it never names an alternative explicitly.

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 when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as sftp_list_dir or sftp_read variants. The agent gets no signal about when this tool is preferred over ssh_exec for reading content.

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

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

With no annotations, the description carries the full behavioral burden. 'Instantly rollback' implies a mutating, destructive overwrite, but the description never states that the current file contents are replaced (data loss), what happens if no .matlock.bak exists, whether permissions are required, or what the result is. Only the snapshot source is disclosed.

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 with zero filler, correctly leading with the action and the target mechanism. It is arguably too terse for a destructive operation, but as a structure/conciseness matter it is efficient and well-ordered.

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 destructive rollback tool with a nested SSH target object, no annotations, and no output schema, the description is materially incomplete. It omits overwrite/data-loss semantics, failure behavior when no backup exists, and any relation to the sibling write tool, leaving an agent unequipped to call it safely.

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 filePath, backupPath, and the nested SSH target fields; the baseline is 3. The description's mention of the '.matlock.bak snapshot' loosely maps to backupPath but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (rollback) and resource (modified remote file) and names the exact snapshot mechanism (.matlock.bak). It does not explicitly differentiate itself from siblings like sftp_write_safe or sftp_read_file, but the operation is clear enough for an agent to select it.

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 gives no explicit when/when-not guidance. It does not say this is meant to undo a prior sftp_write_safe, that a valid snapshot must already exist, or how it relates to the alternative of re-writing the file. Usage must be inferred 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses the backup naming scheme (.matlock.bak.<timestamp>), that the write is atomic, and that the response includes a unified diff and SHA-256 hashes. It stops short of stating what happens when an existing backup is present, whether parent directories are created, or required permissions.

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 dense sentence with the key value proposition ('Safe atomic') front-loaded and the three side effects listed after a colon. Zero filler, though the crammed list is slightly harder to parse than separate clauses would be.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential traits: it is destructive-ish (overwrites a remote file), it makes a timestamped backup, and it returns diff and SHA-256 evidence. Remaining gaps (error behavior on missing paths, directory permissions) are minor and mostly addressable by the required 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 100%, so every parameter including the nested target object is already documented, making 3 the baseline. The description's mention of backup creation and diff/hash output loosely relates to createBackup but adds no syntax or format detail 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?

The description states a specific verb and resource ('atomic remote file write') and enumerates three concrete behaviors: backup creation, atomic write, and returning a diff plus SHA-256 hashes. It clearly separates this from sftp_read_file, but it never names or contrasts with the closest sibling, sftp_rollback_file, which is the natural pair for this 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?

The word 'Safe' hints at intent, but there is no explicit when-to-use guidance and no mention of alternatives such as ssh_exec or the relationship to sftp_rollback_file. An agent must infer that it should prefer this over writing a file via ssh_exec, and no exclusions or preconditions are given.

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

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

With no annotations, the description carries the full burden. It usefully discloses the containment tiers, destructive-operation blocking, and that assertions run post-flight (ports, processes, files). It omits what happens when a command is blocked or an assertion fails, and says nothing about execution/auth behavior beyond the schema's key-vs-password note.

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 dense sentence that front-loads the action and then the safety machinery; no wasted filler. The faintly marketing tone ('Matlock 3-Tier blast-radius') is tolerable but slightly reduces crispness.

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 destructive-capable tool with nested params, no annotations, and no output schema, the description covers the guardrail story but leaves notable gaps: return format, assertion-failure behavior, and timeout/blocking semantics. Adequate but not complete.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema; baseline is 3. The description adds only a general mention of assertions (listening ports, process liveness, file existence) that the schema already enumerates, so it adds little param-level value.

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

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

States a specific verb+resource ('Execute shell command on remote host') and adds distinguishing machinery (3-Tier blast-radius containment, post-flight assertions). It doesn't name a sibling to contrast against (e.g. ssh_exec_background), so it falls short of a 5, but the core purpose is 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?

Implies when it applies by warning that destructive operations are blocked unless confirmed, which tells the agent a confirmDangerToken path exists. However it never says when to prefer this over ssh_exec_background or ssh_task_poll for long-running work, leaving sibling routing to inference.

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

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

With no annotations, the description carries the burden and does add real value: it discloses the detached subshell mechanism, the timeout-avoidance rationale, and that a taskId is returned as the handle for later polling. It omits failure/auth behavior and whether logs persist, but the core lifecycle is conveyed.

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, front-loaded with the action and mechanism, then the return contract. No filler; every clause 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?

For a background-exec tool with no output schema and a fully documented nested target schema, the description supplies the key missing piece: the return value (taskId) and its polling purpose. Remaining gaps (error handling, log retention) are minor.

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%, including the nested target object, so the schema already defines every parameter. The description only references taskId implicitly via polling, adding nothing beyond what the structured fields provide — the baseline 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?

States a specific verb (launch) and resource (long-running command) plus the execution mode (detached background subshell). This implicitly distinguishes it from the synchronous ssh_exec sibling, since an agent knows foreground vs background from the description alone.

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?

"Long-running command" and "avoids client timeout" give a clear condition for selecting this over ssh_exec, and the mention of polling logs/status points toward ssh_task_poll. It stops short of explicitly naming those siblings or stating when NOT to use it.

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 discloses a genuine behavioral trait (single round-trip, bundling many reads) and implies a read-only telemetry operation, but never states it is non-destructive, whether it needs sudo for some sections (Docker, ports), or what happens on connection failure. Partial coverage only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the enumerated payload list is dense but each item earns its place by telling the agent what data it will get back. Slightly list-heavy but appropriately sized.

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 usefully catalogs the returned data categories, which is its main contribution. However, it omits auth/permission expectations, failure behavior, and confirms nothing about safety for a tool that opens an SSH session to a remote machine.

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?

One nested parameter with 100% schema description coverage, so the schema already documents host, port, profile, username, password, and privateKeyPath. The description adds nothing about the target/profile resolution beyond what the schema's own descriptions say (default profile 'homelab'). 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?

States a clear resource (remote host) and enumerates exactly what the snapshot returns: OS, kernel, uptime, load, RAM, disk, Docker, ports, top processes. This distinguishes it from ssh_exec (arbitrary command execution) without naming siblings. Specific and concrete, though it never explicitly contrasts itself with the exec/sftp family.

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?

Usage is implied rather than stated: 'in a single round-trip' hints that this is preferable to multiple ssh_exec calls when you want a broad host overview. There is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the routing decision.

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

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

With no annotations, the description carries the full burden and does a good job: it discloses the workflow, side effects (installing the public key, saving a profile), and prerequisites (password). It lacks details about idempotency, overwrite behavior, failure handling, or security caveats like where the private key is stored.

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 definition is a single front-loaded sentence that leads with the tool name and conditional, then lists the actions in order. It is dense but every clause is substantive, 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?

For a complex, six-parameter mutating tool with no annotations and no output schema, the description adequately covers the purpose and end-to-end workflow. It falls short of full completeness by omitting failure modes, security considerations, and what the tool returns after verification.

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 six parameters thoroughly. The description only alludes to the saved profile and generated key, adding no parameter syntax or constraints beyond what is already in 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?

The description states a specific verb (bootstrap) and resource (SSH key) and enumerates the exact steps: generating a local key pair, connecting via password, installing the public key, verifying key login, and saving a profile. It distinguishes itself from execution-oriented siblings by requiring only a VPS password and implying a one-time setup scenario.

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 gives a clear condition for use: 'If you only have a VPS password.' This tells the agent exactly when to choose this tool over key-based alternatives, though it never names a sibling tool explicitly or states when not to use it.

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 behavioral burden. It discloses the storage location, but for a mutation tool (save/remove) it says nothing about reversibility, side effects, required permissions, or how existing profiles are affected — significant gaps for zero annotation coverage.

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 that names the operations, the resource, and the persistence location with zero filler. Nothing is wasted.

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

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

For a tool with a nested object parameter, no annotations, and no output schema, the description covers purpose and storage path but omits mutation behavior and result expectations. The schema handles parameter structure, but the behavioral gap keeps it at a minimum-viable level.

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%, and the schema already encodes the action enum and the 'required if action is save/delete' conditions for the other parameters. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific set of verbs (List, save, remove) against a clear resource (saved SSH host profiles) and even names the storage file (~/.matlock/profiles.json). This clearly separates it from execution/transfer siblings, though it doesn't explicitly contrast with any named alternative.

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 lists the supported operations but gives no guidance on when to use this over a sibling (e.g., ssh_exec or ssh_key_bootstrap), no prerequisites, and no conditions for choosing an action. The agent is left to infer usage from the enum 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?

No annotations are provided, so the description carries the full burden. It does not say whether termination is irreversible, whether the task record is removed or merely signaled, or what SIGKILL does versus SIGTERM beyond the schema's enum; 'terminate or signal' leaves the lifecycle effect ambiguous.

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 sentence with no filler, front-loading the verb and the required identifier. Nothing in it is redundant or padded.

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 destructive lifecycle operation with no annotations and no output schema, the description is thin: it omits irreversibility, the fate of the task after signaling, and whether target is needed only for cross-host tasks. The schema covers parameters but the description does not compensate for the missing safety profile.

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%, including signal default (SIGTERM), port default (22), and target fallback behavior, so the schema already does the heavy lifting. The description adds nothing beyond what the schema documents, which is the baseline case.

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?

Clear specific verb ('Terminate or signal') plus resource ('running background task') and an identifying key ('by taskId'). This is implicitly distinct from siblings like ssh_task_poll (status) and ssh_exec_background (creation), though no sibling is named explicitly.

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 statement of when to use this versus ssh_task_poll or how to reap the result, and no mention that the task must have been started by ssh_exec_background. The only contextual hint (target omitted → default profile 'homelab') lives in the schema, not the 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?

No annotations are provided, so the description carries the full behavioral burden. "Check" and "inspect" imply a non-destructive read, which is useful, but it does not say whether polling is safe to repeat, whether the task is consumed/cleared, or whether the call blocks – gaps that matter for a no-annotation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the resource comes first and the operation list follows efficiently.

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

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

With no output schema, the description does enumerate what is returned (status, exit code, log tail), which is the key missing piece. It does not cover whether the task persists or is cleared after polling, a minor gap given the otherwise complete coverage.

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%, including the nested target object, taskId, and tailLines, so the schema already documents all three parameters. The description adds no format or default detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb set (check status, exit code, inspect log tail) against a specific resource (a background task launched via ssh_exec_background). An agent can distinguish this from ssh_exec, ssh_exec_background, and ssh_task_kill without opening any 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?

Clearly ties itself to tasks launched via ssh_exec_background, which gives strong usage context. However, it never states when NOT to use it or names the alternative for stopping a task (ssh_task_kill), so routing guidance is context-rich but not complete.

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