MCP SSH Manager

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, and it delivers. It identifies set as mutating, names the exact config file path, notes write-access requirements, explicitly labels get and check as read-only, reveals the default for enabled, and flags the error case for 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 well-structured: a high-level purpose statement followed by a compact breakdown of the three actions and their side effects. Every sentence adds necessary information, and the mutating/read-only distinction is front-loaded rather than buried.

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 six parameters and no output schema, the description covers actions, side effects, permissions, defaults, and error conditions well. It stops short of describing the exact shape of get/check return values, but the verbal descriptions of 'reads back that config' and 'compares them to stored thresholds' give an agent enough operational clarity.

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 baseline is 3. The description adds real value by explaining what the action parameter does for each enum value and by clarifying the enabled default and check error behavior, which the schema alone does not convey. That warrants a step above baseline.

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-resource pairing: 'Configures and evaluates CPU, memory, and disk usage alert thresholds for a remote server.' It then enumerates the three action modes, making it clear this tool manages alert thresholds rather than performing general SSH execution or monitoring.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly explains when to use set, get, and check, and includes important constraints like 'blocked on readonly servers' and 'check errors if no config exists yet.' It does not explicitly compare this tool to sibling tools, but the action-specific guidance is strong enough for an agent to route usage correctly.

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 effectively discloses that add and remove persist the alias mapping locally, list is read-only, and add requires the target server to already exist. It doesn't mention error handling (e.g., duplicate alias, removing a non-existent alias) but covers the core side effects and prerequisites.

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 three sentences, each earning its place: first sentence states the overall purpose, second explains the action parameter and per-action requirements, third covers persistence and the prerequisite for add. It is front-loaded with the core purpose and avoids unnecessary words or padding.

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 three-parameter tool with an enum action and no output schema, the description is largely complete. It covers all actions, required parameters, persistence behavior, and the add prerequisite. It omits specifics about return values (e.g., what list returns) and error cases, but these are minor for a CRUD-like alias manager. Given the simplicity, the description is sufficient for correct invocation.

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

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

Schema coverage is 100% with basic descriptions for each parameter. The description adds meaning by explaining the 'action' parameter selects add/remove/list, that 'alias' is required for add and remove, and 'server' is required for add. This goes beyond the schema's generic descriptions (e.g., 'for add/remove') by specifying conditional requirements and the role of each parameter in different actions.

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

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

The description clearly states the tool's purpose: 'Manages local name aliases that let you reference a configured server by a shorter or alternative name.' It then breaks down the three actions, making the function unambiguous. Though it doesn't explicitly name ssh_command_alias as a distinct sibling, the focus on 'server' aliases versus 'command' aliases makes the differentiation clear without reading 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 implies when to use the tool (when you need to manage server name aliases) but provides no exclusions or references to sibling tools. It doesn't explicitly say 'use this instead of ssh_command_alias' or mention alternative tools for similar operations. The usage context is implied through the purpose, but the lack of explicit comparison or 'when not to use' guidance leaves a gap.

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. It candidly discloses side effects: writing two artifacts, pruning old backups by retention, running pre/post hooks, defaulting compression, and erroring on 'full'.

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

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

Four compact sentences front-load the core action and artifact description, then pack defaults, pruning behavior, and hooks without redundancy. Every sentence contributes operational value.

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 13-parameter remote mutation tool with no annotations and no output schema, the description covers essential conditions, defaults, side effects, and the failure mode for unsupported types. An agent has enough to validate inputs and anticipate consequences before calling.

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 baseline is 3. The description adds valuable cross-parameter constraints: database types require database, files requires paths, and defaults for retention, compress, and backupDir. This goes 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 concrete action ('Creates...backup'), identifies the transport ('over SSH'), and specifies the output artifacts ('compressed archive plus a JSON metadata file'). The supported types and explicit 'full' error help distinguish it from sibling backup tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly communicates the use context: on-demand SSH backups with type-specific prerequisites and an unsupported full mode. It doesn't explicitly say when to prefer this over ssh_db_dump or ssh_backup_schedule, but the context is strong enough for an agent to infer the intended use.

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 explicitly states 'Read-only: it inspects the filesystem and mutates nothing', which is a key behavioral disclosure. It also mentions that it parses metadata from stored metadata, providing transparency on the operation's nature.

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, front-loaded with the primary purpose, and every sentence adds relevant detail without redundancy. No fluff or unnecessary information.

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

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

For a list operation, the description is complete: it specifies the resource, optional filters, defaults, and the output fields. It does not mention error scenarios or authentication, but these are not typically required for a read-only list. The information provided is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reiterates the type enum and the backupDir default, which are already in the schema, but adds value by explaining the purpose of the 'type' filter and the output fields. It does not significantly extend beyond what the schema already provides.

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 ('Lists existing backups'), the resource (backupDir on remote server), and enumerates the returned fields. It is distinct from sibling tools like ssh_backup_create or ssh_backup_restore by focusing on listing/inspection.

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 explains how to invoke the tool (optional type filter, backupDir default) but does not explicitly state when to use it versus alternatives, such as 'use this to view backups instead of creating/restoring'. No exclusions or alternative tool names 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, and it delivers: it explicitly warns that the operation is destructive and overwrites the target, details per-engine behavior (pg_restore --clean --if-exists, mongorestore --drop, MySQL piping), and mentions pre/post-restore hooks. This is exemplary disclosure.

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 four focused sentences: main action first, then destructive warning, then engine-specific details, then supported engines and hooks. Every sentence adds value; 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?

For a destructive restore operation with no annotations or output schema, the description covers the essential behavioral facts, engine differences, supported engines, and hooks. The only notable gap is the lack of any statement about return values, success/failure indication, or required preconditions beyond the existence of the backup.

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 context about engine selection via metadata but does not elaborate on individual parameter semantics beyond what the schema already provides. No deduction is warranted given the full 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 opens with a specific verb and resource: 'Restores a previously created backup identified by backupId'. It also explains the engine-selection mechanism, which distinguishes this from siblings like ssh_backup_create and ssh_db_import. The purpose is immediately 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 phrase 'previously created backup' clearly ties this tool to backup-creation workflows, and the supported engines are listed. However, it does not explicitly name alternative tools such as ssh_db_import or state when one should be preferred over the other, leaving some 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 provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool mutates the remote filesystem and crontab, writes an executable script to a specific path, typically needs root, and that the generated script deletes old backups based on retention. This is unusually transparent for a mutating 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?

Three sentences, each earning its place: first states the core scheduling action, second discloses side effects and permissions, third lists supported types and default retention. The information is front-loaded and free of 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?

The description is largely complete for a 7-parameter tool: it explains side effects, permission needs, supported backup types, and the retention default. The main gap is that it does not clarify conditional parameter requirements, such as paths being needed when type=files, though the schema partially signals this.

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 baseline is 3. The description adds some context by referencing the cron expression, supported backup types, and retention default, but it does not need to deeply explain individual parameters because the schema already documents them well.

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 gives a specific verb and resource: it 'schedules a recurring backup' by writing a script and installing a crontab entry. It clearly distinguishes itself from one-off siblings like ssh_backup_create and restore by emphasizing recurrence via cron.

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 makes the usage context clear: recurring backups via cron on a remote server, with explicit mention of requiring root to write the target path. It does not explicitly name an alternative for one-off backups, but the recurring/cron framing is sufficient to route an agent correctly.

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 transparency burden and does well by disclosing no remote execution, no side effects, local config storage, and overwrite-on-add behavior. It does not mention result format, error handling, or config file location, so it stops short of 5.

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?

Three sentences, all substantive and well organized: main purpose first, action semantics second, and the overwrite caveat last. There is no filler, and nothing merely repeats the schema.

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 no output schema or annotations and four distinct actions, the description explains each action's behavior and even gives high-level return expectations for list and suggest. It does not specify exact result formatting or failure behavior, but an agent has sufficient information to select and invoke the tool correctly.

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

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

Schema coverage is already 100%, and the description adds meaningful operational detail beyond the schema by binding each action to its required parameters (e.g., command doubles as the search term for suggest, add needs both alias and command). This mapping is not fully inferable from the enum alone.

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 resource ('local shorthand aliases' mapping a short name to a full command string) and scopes behavior to local config with no remote execution, which distinguishes it from the many remote-execution siblings. It falls short of 5 because it does not explicitly differentiate from the similarly named 'ssh_alias' sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers clear action-specific usage guidance: add requires both alias and command, remove requires alias, suggest uses the command field as a search term, and list shows profile/custom-tagged aliases. The 'local config with no remote execution or side effects' phrase gives selection context versus remote tools, although no alternative tool is named explicitly.

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 transparency burden and largely meets it: status is labeled read-only, reconnect closes then reopens, disconnect closes, cleanup drops aged-out/dead connections, and all effects are confined to local in-memory state. It stops short of noting failure modes or in-flight operation impact.

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 dense sentences: the first sets scope and the second maps actions and parameters. Every clause carries useful information 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 two-parameter tool with no output schema, the description fully equips an agent to choose an action, supply server when required, and anticipate the local-only side effects. Nothing critical for correct invocation is missing.

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 schema describes both parameters, the description adds real semantic value by explaining each action enum value's effect and the conditional requirement/ignored behavior of server. This is precisely the disambiguation an agent needs beyond the generic schema text.

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 identifies the tool as inspecting and managing pooled SSH connections held by the local server process, then breaks it into four explicit actions. The 'never remote state' boundary distinguishes it from sibling SSH tools that operate on remote servers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete action semantics and states exactly when the server parameter is required versus ignored. It does not name sibling alternatives explicitly, but the local-only/never-remote scoping gives an agent enough context to avoid using it for remote-state operations.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It transparently notes that the database is not modified, explains engine-specific flags, states that compression defaults to true with gzip, and warns that the tables list is ignored for MongoDB. It could also clarify overwrite behavior for an existing output file, but the core side effects are 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?

The description is dense but efficient. The main purpose is front-loaded in the first sentence, and every subsequent sentence adds non-obvious operational detail without repetition 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?

For a 10-parameter tool with no output schema, the description covers the most important operational nuances: read-only behavior, database-specific flags, compression, and table-list limitations. It is slightly incomplete regarding what happens if the remote output file already exists and what the tool returns after completion, but these are minor 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%, so the baseline is 3. The description adds meaningful context beyond the schema: MySQL flags, PostgreSQL custom format and pg_restore compatibility, the compression default, and the MySQL/PostgreSQL-only behavior of the tables parameter.

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

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

The description states a specific action, 'Dumps a database to a file on the remote server over SSH,' and clarifies it 'reads data only and does not modify the database.' This clearly differentiates it from sibling tools like ssh_db_import, ssh_db_query, and ssh_db_list.

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 clear context for when to use the tool by emphasizing read-only behavior and listing supported database types. It does not explicitly name alternative tools for write operations, but the read-only framing makes the intended use unmistakable.

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 present, the description fully carries the behavioral burden. It explicitly discloses destructive behavior, the exact PostgreSQL DROP semantics, MongoDB's --drop default, MySQL's replacement behavior, and automatic .gz decompression.

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?

Three tightly packed sentences front-load the most critical fact (destructive), then give DB-specific behavior and supported input handling. No filler or redundant restatement of schema fields.

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 covers the essential operational facts for a destructive import tool: supported database engines, per-engine destructive behavior, the drop flag's default, and compressed input handling. No output schema is present, but return values are not necessary for an agent to invoke this correctly; the missing details are optional parameters already documented by the 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?

Schema coverage is 100%, so the schema already documents all parameters. The description clarifies the drop flag and database-type-specific behavior, but it does not add substantial new detail about most parameters such as server, database, dbHost, dbPort, or inputFile.

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 action ('imports a dump file into a target database') with a specific resource and context (remote server). Distinguishes itself from sibling tools like ssh_db_dump and ssh_db_query through the explicit import and destructive-restore framing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context by naming supported database types and explicitly warning that the operation is destructive. Does not name alternative tools or when-not-to-use conditions, but the import purpose is unambiguous enough for an agent to select it over export/query 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?

With no annotations provided, the description carries the full burden and does well by stating the operation is non-modifying, read-only, safe to call repeatedly, and filters system databases. It could add details about authentication or error behavior, but the key behavioral traits are 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?

The description is three compact sentences, front-loaded with the core purpose and safety guarantee. Every sentence earns its place, and there is no redundant phrasing or repeated schema content.

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

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

For a list-style tool with no output schema, the description covers purpose, parameter-dependent behavior, supported engines, return shape, and safety profile. It could mention how credentials are resolved or what happens on connection failure, but nothing critical is missing for selecting and invoking the 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 documents all parameters with descriptions, so the baseline is 3. The description adds meaningful context beyond the schema by explaining how the 'database' parameter changes behavior, which engines are supported, and what the return payload contains.

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 ('Lists') with a clearly defined resource ('database objects on the remote server') and states it modifies nothing. It also distinguishes its behavior from siblings like ssh_db_query, ssh_db_dump, and ssh_db_import by focusing on introspection only.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: when 'database' is provided it lists tables/collections, and when omitted it lists databases with system databases filtered out. It also notes the tool is read-only and safe to call repeatedly, but it does not explicitly name alternatives or state when to prefer another tool.

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 so thoroughly: it explains pre-execution keyword validation, that the statement then runs inside a read-only transaction so the database itself refuses writes, and the MongoDB-specific bans on $where/$function/$accumulator. It also discloses the return format as raw command text.

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?

Three dense sentences that are front-loaded with the core read-only contract before the per-dialect rules; nothing is filler. It is somewhat long, but the length is driven by genuinely distinct per-dialect behavior rather than padding.

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?

Covers the 9-parameter, 3-dialect surface plus the conditional MongoDB requirement, and explicitly states the return value ('raw command output as text') even though no output schema exists. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it states that the MongoDB path requires the collection parameter (which is not listed in the schema's required array), that query must be a filter document, and that mysql/postgresql query must begin with SELECT.

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 (runs) plus resource (read-only query against a remote database) and constrains the operation to SELECT/find, which cleanly separates it from write-oriented siblings like ssh_db_import and ssh_db_dump. An agent can tell what this does 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 read-only framing and the enumerated rejections (insert, update, delete, drop, exec, $where, etc.) effectively communicate when this tool is and isn't usable, and imply that write work belongs elsewhere. It stops short of naming a concrete alternative such as ssh_db_import for writing or ssh_db_list for enumeration.

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 to carry safety/behavior information, the description carries the full burden and does so richly. It discloses mutation of remote state, the temporary-upload-before-move sequence, backup-on-overwrite behavior, sudo password usage, hook execution, and blocking on readonly/restricted servers.

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?

Every sentence in the description earns its place; the core action and mutation warning are front-loaded, followed by backup, option coverage, defaults, hooks, and the security-mode blocker. Despite covering many facets, it stays compact and 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 state-mutating deployment tool with nested parameters and no output schema, the description covers almost everything an agent needs: mechanics, backup behavior, options, defaults, hooks, and security restrictions. It does not describe the return format or failure cleanup behavior, which keeps it from a 5.

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 baseline is 3, but the description adds real meaning beyond the schema: it explains that each file is uploaded to a temporary location before being moved, that backup is on by default and can be disabled, that owner/permission defaults are detected from the remote path, and that restart targets a single service. This enriches the bare parameter names.

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 opening sentence states a specific action, resource, and target: deploying a list of local files to remote paths on a named server, with a distinctive temp-then-move mechanism. It is clear, but it never explicitly contrasts with closely related siblings such as ssh_upload or ssh_sync, so differentiation is left to inference.

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 clear operational context: use for multi-file deployment with backup defaults, owner/permission handling, hooks, optional service restart, and a hard exclusion on readonly/restricted servers. It does not explicitly say when to prefer this over ssh_upload or ssh_sync, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses side effects ('overwriting any existing local file'), remote-side scope ('read-only on the remote side'), permission requirements ('configured SSH user, which must have permission to read it'), and operational constraints (single file 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?

Three information-dense sentences front-load the action, then add constraints and alternatives in a logical order. Every sentence 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?

For a three-parameter tool with no output schema, this description is complete. It covers action, side effects, permission requirements, security-mode compatibility, and the directory alternative. An agent has enough to decide when to use it and how to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description augments the schema by explaining that localPath will be overwritten and that remotePath must be readable by the SSH user, which adds meaningful operational context to the parameter behaviors.

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

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

The description opens with a specific action and resource: 'Downloads one remote file from the named server to a local destination path over SFTP.' It explicitly clarifies the single-file scope and points to ssh_sync for directories, making it unmistakably distinct from siblings like ssh_upload and ssh_sync.

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 directly states when to use the tool versus alternatives: 'Handles single files only; use ssh_sync for directories.' It also provides a contextual prerequisite—allowed even on servers in readonly or restricted security mode—which helps the agent decide suitability without external lookup.

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 fully carries the burden of behavioral disclosure. It explicitly states that the tool mutates remote state, expands aliases, handles cwd fallback, adapts to Linux/Windows, has timeout limits, enforces readonly/restricted mode restrictions, and truncates large output. This is comprehensive transparency.

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

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

The description is front-loaded with the core purpose in the first sentence, then adds details in a logical sequence: mutation, alias expansion, cwd, OS adaptation, timeout, mode restrictions, and truncation. Every sentence carries unique information without redundancy, making it efficient for its depth.

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 general execution tool with 4 parameters and no output schema, the description covers return values, edge cases (truncation, mode restrictions), configuration defaults, and behavioral nuances. It is complete enough for an agent to call correctly without missing critical information.

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 each parameter has a description. The description adds value beyond the schema by explaining cwd fallback behavior, timeout default and cap, and command alias expansion, which clarifies the operational context of these parameters.

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

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

The description clearly states it runs a shell command over SSH and returns stdout, stderr, and exit code. It distinguishes itself from siblings by detailing alias expansion, OS-adaptive syntax, and timeout behavior, enabling an agent to recognize it as the generic execution tool even without naming alternatives.

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 explicitly say when to use this tool versus siblings like ssh_execute_sudo or ssh_execute_group. It provides behavioral context such as not being read-only and mode restrictions, but the selection criteria are implied rather than stated, leaving the agent to infer 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 full burden and does so thoroughly: it discloses remote mutation, non-idempotence, per-server policy failures, best-effort semantics, stopOnError interaction, strategy meaning, timeout, and cwd default. There is no contradiction with annotations.

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

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

Four dense sentences front-load the primary action and return value, then add only high-value behavioral detail. No filler or repetition of schema text.

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 group command with no annotations and no output schema, this description covers membership resolution, failure semantics, strategies, timeout, and cwd default. The only mild gap is an exact report format, but 'per-server success or failure report' is sufficient for invocation.

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

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

Schema coverage is 100%, but the description adds material behavior beyond the schema: group membership can exist through config alone, cwd defaults to default_dir, timeout is 30000 ms, and stopOnError only changes the best-effort abort behavior. It also clarifies how delay applies to the rolling strategy.

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?

Opens with 'Runs one command on every server belonging to the named group', naming a specific verb, target resource, and group scope. This clearly separates it from single-host tools like ssh_execute and from ssh_execute_sudo.

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 makes the intended context clear: group-wide execution over servers derived from ssh_group_manage or host config. It also explains best-effort failure handling, strategies, and stopOnError, but does not explicitly state when to prefer an alternative such as single-server ssh_execute.

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 at all, the description carries the full disclosure burden and more than meets it. It flags that the command 'mutates remote state and can be destructive,' explains sudo -S password piping and output masking, notes readiness for Linux/Windows, cwd honoring, timeout defaults, and readonly/restricted mode constraints. This is exemplary behavioral transparency.

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

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

The description is dense but well-organized, front-loading the purpose and then layering behavioral details. Each sentence adds distinct value: password handling, mutability/destructiveness, directory and OS behavior, timeout, and execution modes. Slightly long but no 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?

Despite lacking an output schema, the description explicitly states the return value (exit code and output) and addresses key context signals: parameters, default timeout, OS adaptation, cwd behavior, and restricted/readonly execution constraints. This is sufficient for an agent to invoke and interpret the tool correctly.

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

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

The input schema covers all five parameters with descriptions, yielding 100% coverage. The description adds valuable semantics beyond the schema by explaining password piping and masking, the timeout default, cwd honoring, and sudo prepending, giving the agent operational details the schema does not convey.

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 precise, specific verb phrase: 'Runs a command with elevated privileges via sudo on the named server and returns the exit code and output.' This clearly identifies the action, the target resource, the elevation mechanism, and the expected result, making it readily distinguishable from the sibling ssh_execute tool.

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 establishes a clear use context: elevated sudo privileges on a named server, with caveats about password handling and readonly/restricted mode behavior. It does not explicitly name alternatives or state 'when not to use,' but the sudo focus implicitly differentiates it from plain ssh_execute.

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 behavioral disclosure burden and does well: it states persistence to local configuration only, absence of remote side effects, and that list also reports read-only derived groups. It does not cover failure semantics or idempotency, but the main safety-relevant behaviors are 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?

The description is dense but well-organized: first sentence states purpose and scope, second defines the operation contract, and third explains read-only behavior and optional defaults. Every sentence earns its place with no 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?

The description covers action semantics, per-action parameter requirements, persistence scope, read-only behavior, and default execution options. It does not describe return values or error behavior for create/update/delete, but the tool is otherwise sufficiently scoped for an agent to invoke it correctly.

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

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

The description adds substantial value beyond the schema's 100% parameter coverage by specifying conditional requirements: list is exempt from name, add/remove require non-empty servers, and strategy/delay/stopOnError serve as default execution behavior. These relationships are not encoded in the input schema, making the prose essential.

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 compound operation—'Creates, updates, deletes, and inspects named server groups'—and identifies the resource scope as local configuration with no remote side effects. It also names the dependent sibling, ssh_execute_group, distinguishing this management tool from execution tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit per-action usage requirements: list is read-only, all other actions require name, and add-servers/remove-servers require a non-empty servers array. It does not explicitly name a competing alternative, but it clearly positions the tool as local group management in contrast to remote-execution 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool is read-only ('only reads metrics and changes nothing') and describes the output structure (parsed JSON, critical_issues list). It also mentions the default value of 'detailed' and what it includes. It does not cover error handling, authentication prerequisites, or behavior on SSH failure, but for a health check these are secondary. The disclosure is strong but not exhaustive.

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 four concise sentences, each adding a distinct piece of value: purpose, safety guarantee, parameter behavior, and output highlights. It is front-loaded with the primary purpose and avoids redundancy. No sentence is wasted; the structure is efficient and informative.

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 moderate complexity (2 params, no output schema, but no nested objects) and the fact that there are no annotations, the description is remarkably complete. It specifies the return format (parsed JSON), the key fields (status, CPU, memory, disk, uptime, critical_issues), and parameter behavior. The only missing aspects (error handling, auth details) are likely standard across the ssh_* family and adequately implied by the context. Nothing essential for correct invocation is absent.

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 baseline is 3. The description adds meaning beyond the schema: for 'detailed', it clarifies the default (false) and the specific additional metrics (load average and network). For 'server', it implies a predefined named server rather than arbitrary host string. These additions exceed the schema's minimal descriptions, thus warranting a 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 states a specific verb ('Runs'), a resource ('the named server'), and a defined outcome ('returns parsed JSON with overall status, CPU, memory, disk usage, and uptime'). It clearly distinguishes this from siblings like ssh_execute (arbitrary commands) and ssh_monitor (likely continuous monitoring) by emphasizing 'read-only health check' and 'diagnostic shell commands'.

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 one-off health diagnostics and explicitly notes it 'only reads metrics' and 'changes nothing', which suggests safe, non-disruptive use. However, it does not explicitly name alternative tools or state when not to use it (e.g., 'for ongoing monitoring, use ssh_monitor' or 'for arbitrary commands, use ssh_execute'). The context is clear but lacks explicit exclusions.

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

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

With no annotations, the description fully discloses behavior: it opens no SSH connection, is read-only, retains data only for the current process, and does not expose command output. This goes well beyond a basic function statement and gives the agent a precise safety and side-effect profile.

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

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

Front-loaded with the core function, then adds behavioral caveats and filter semantics in a logical order. Every sentence earns its place with no redundant wording or fluff.

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 read-only lookup with four optional parameters and no output schema, the description covers what the agent needs: what is returned (timestamps, server, duration, success status), what is excluded (command output), and the current-session limitation. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining that filters 'narrow the results', that 'search' targets substring in command text, and that 'limit' defaults to the 20 most recent entries. This is extra value beyond the schema's terse field 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?

States the exact action ('Returns the in-memory log of SSH commands') with a specific resource and scope ('through this server process during the current session'). The read-only, local nature and explicit disambiguation from execution tools clearly distinguish it from siblings like ssh_execute or ssh_session_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context that this is for reviewing commands from the current in-memory session only, and explicitly notes it does not persist across restarts. It does not name alternative tools or state when not to use it, but the unique purpose makes usage obvious.

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 transparency burden and handles it well. It explicitly discloses the side-effect profile: changes are local, persistent, have no immediate remote action, and affect later operations. It also describes what list and status reveal, which is useful behavioral context.

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

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

The description is compact and front-loaded with the core resource and key constraint. The main redundancy is the phrase 'The action selects behavior,' which is followed by an explicit enumeration, but the overall structure is dense and 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 two-parameter tool with no output schema, the description is complete: it covers all action branches, parameter usage, side effects, persistence, and the nature of list/status output. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining what each action does and clarifying that enable and disable both require the hook name. This goes beyond the terse schema descriptions and the raw enum values.

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 identifies the resource as SSH automation hooks and names the supported operations: list, enable, disable, and status. The phrase 'local configuration only with no immediate remote action' helps distinguish this tool from remote-execution siblings like ssh_execute and ssh_deploy.

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 explains when each action is appropriate, including that list and status are informational, while enable and disable require a hook name. It also notes the tool only affects local configuration and has no immediate remote action, though it does not explicitly name alternative tools or when not to use this one beyond that scope.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly classifies verify/check/list as read-only, states that accept and remove mutate local state, and warns that autoAccept should be used with caution. It also tells the agent that mutation is blocked on readonly servers, which is essential safety context.

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

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

The description is compact and front-loaded with the tool's purpose, then moves through action semantics and safety conditions. Every sentence contributes information, with no filler or repetition of schema trivia.

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 covers the main actions, mutation risks, readonly blocking, and parameter requirements. However, it does not clearly distinguish verify, check, and list from one another, which could lead an agent to choose the wrong read-only action. Since there is no output schema, some indication of return behavior would also have improved completeness.

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

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

Although schema coverage is 100%, the schema only says 'Action to perform' for action and 'use with caution' for autoAccept. The description adds real semantic value by grouping the enum values into read-only versus mutating operations, clarifying the conditional requirement for server, and giving the default and caution for autoAccept.

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 and resource: it manages SSH host key fingerprints in the local known_hosts file for a named server. It then enumerates concrete actions, making it easy to distinguish from sibling tools like ssh_execute or ssh_tunnel_create.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly explains what each action does and notes that server is required for every action except list. It also mentions that accept and remove are blocked on readonly servers, giving useful usage constraints, though it does not explicitly name alternative tools for comparison.

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 fully covers behavioral traits: read-only, local, opens no SSH connections, and deliberately omits secrets. This is exemplary transparency for a list tool.

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

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

The description is concise and well-structured, front-loading the purpose in the first sentence. Each subsequent sentence adds unique value: return fields, safety, secrets, parameters, and use case.

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

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

For a simple list tool with no output schema, the description is complete: it lists return fields, describes read-only behavior, clarifies no secrets, states no parameters, and gives a concrete usage scenario.

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 is empty and the description explicitly states 'Takes no parameters,' leaving no ambiguity. Since there are zero parameters, no further semantics are required, and the baseline of 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 'Lists all SSH servers defined in the loaded configuration' with specific verb and resource, and enumerates the return fields. It distinguishes itself from sibling tools by being the server list, not sessions or tunnels.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit usage context: 'Useful as a first call to discover which server names other tools accept.' It also notes read-only and local behavior, but does not explicitly name alternatives or 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?

With no annotations available, the description carries the full burden—and it does excellently. It explicitly states the tool is read-only, changes no remote state, requires no sudo, and only gathers a single snapshot even when interval and duration are provided. This is transparent and prevents misuse.

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

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

Four sentences with no filler. The main capability is front-loaded, parameter behavior is explained, and important caveats about monitoring semantics, sudo, and platform support each earn their 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 core call-time decision points are covered: inputs, default behavior, safety, and platform caveats. Since there is no output schema, the description could have been slightly more explicit about the shape or format of the returned snapshot, but the named commands and resource categories give a reasonable expectation.

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

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

The schema already covers all parameters at 100%, but the description adds real value by explaining that type defaults to overview, enumerating its possible values, and clarifying that interval and duration do not actually enable continuous monitoring. This goes beyond the schema without being redundant.

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 and resource: 'Collects a read-only snapshot of system resources on the named Linux server.' It also names the inspection commands and the type parameter's view options, which clearly distinguishes it from execution, transfer, session, and tunnel siblings.

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 clear context for when the tool is appropriate: read-only monitoring without state changes or sudo, and notes a Linux-only expectation with potential empty output on Windows. It does not explicitly name alternatives like ssh_execute or ssh_execute_sudo, so it falls just short of a 5.

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

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

With no annotations present, the description properly carries the behavioral disclosure burden: it explicitly marks list and info as read-only, kill as mutating remote state, and notes the readonly-server block. It also exposes defaults for signal, sortBy, and limit, which helps the agent predict 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?

Three dense sentences cover actions, read-only vs mutating behavior, required parameters, constraints, and defaults. The most important behavioral distinction is front-loaded, and every sentence earns its place without fluff.

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 7 parameters, 3 enums, and no annotations or output schema, the description covers the essential invocation requirements: action selection, pid requirement, readonly constraint, and default behavior. It does not detail the output shape, but it communicates enough for correct selection and basic invocation.

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

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

Input schema coverage is 100%, so the baseline is 3. The description mostly repeats information already in the schema property descriptions, such as pid being required for kill/info, filter narrowing by name/command, and the defaults for signal, sortBy, and limit. It adds little novel semantic meaning 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 uses specific action verbs ('Lists, inspects, or terminates processes') and names the resource (processes on a remote server over SSH). It clearly distinguishes the three modes via the action parameter, making it immediately obvious 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?

The description gives clear context for when each action is appropriate: list and info are read-only, kill mutates state, and kill is blocked on readonly servers. It states that pid is required for kill and info, but it does not explicitly compare this tool to sibling alternatives like ssh_execute.

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 so well: it states the tool's local-only scope, no remote side effects, that switch requires a profile argument, and that a successful switch requires a Claude Code restart.

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?

Three dense sentences, each earns its place: scope/safety, action semantics, post-switch behavior. 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 simple enum-driven tool with no output schema, it describes what list/current return and what switch reports, plus side-effect scope. Nothing essential is missing.

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 baseline is 3. The description adds semantic meaning by explaining what each action does, and by specifically tying the profile parameter to the switch action as required.

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?

Identifies a specific resource (SSH Manager profiles) and the concrete operations (list, current, switch), and immediately disambiguates from the remote-action sibling tools by stating local configuration only, no remote side effects.

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?

Conveys clear context: use when working with project-type profiles, and explicitly warns that only local configuration is affected. Does not name alternatives or state when not to use, so it stops short of a 5.

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

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

With no annotations provided, the description carries the behavioral disclosure burden and does well: it explicitly says the operation is read-only, describes the JSON response shape, counts, and health rating, and explains automatic name resolution. It doesn't cover error handling or authentication requirements, but the core behavior is 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?

Three focused sentences: what it does and returns, its read-only safety guarantee, and essential parameter guidance. No filler or repetition of schema content.

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

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

The description covers the operation, safety profile, parameter requirements, name resolution behavior, and return value shape, which is especially important given there is no output schema. Minor gaps like error behavior and how the server is identified are not fully addressed, but the agent has enough to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by stating services is required, giving concrete examples, and explaining that common names are resolved to unit names automatically. This goes beyond the schema's simple 'Service names to check' 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?

Description clearly states the tool checks the running state of services over SSH and lists the key outputs. However, it does not explicitly distinguish itself from closely related siblings like ssh_process_manager or ssh_health_check.

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 makes it clear this is for inspecting service status rather than changing it, so usage context is implied. But it does not explicitly state when to prefer this tool over alternatives or 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?

With no annotations present, the description carries the full burden, and it delivers: it discloses destruction of session state, that remote files are not deleted, that 'all' closes every session while ignoring individual errors, and that the pooled underlying connection is retained. This is far beyond minimal disclosure for a mutating 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?

Every sentence adds a distinct, valuable fact: the core termination behavior, the destructive scope, the special 'all' semantics, and the pooled-connection nuance. There is no filler, and the most important information appears first.

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 one-parameter destructive action with no output schema, the description covers everything an agent needs to invoke it correctly: required input format, edge cases ('all'), side effects, and what it does not affect. The description is self-sufficient even though no return-value details are provided.

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

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

The schema already covers the single parameter at 100%, including the special 'all' value. The description adds meaningful behavioral detail beyond the schema, such as the fact that 'all' ignores individual close errors and that the session ID becomes unusable afterward.

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

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

The description names a specific verb and resource: it terminates an SSH session by session ID, with details about writing exit, discarding history/context, and invalidating the ID. It clearly distinguishes itself from sibling tools like ssh_session_start, ssh_session_send, and ssh_session_list.

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 makes the tool's function obvious, but it does not explicitly state when to prefer this tool over alternatives or mention any exclusions. The use case is strongly implied—closing sessions started by ssh_session_start—but the description does not spell out the relationship with sibling 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 present, the description carries full responsibility and delivers: it states the operation reads in-memory session state, changes nothing on remote hosts or local config, and excludes closed sessions. This is exactly the behavioral context an agent needs to safely invoke an inspection 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?

Three sentences, each earning its place: the first defines the tool's output, the second establishes safety, and the third explains parameter behavior. Information is front-loaded 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?

For a simple one-parameter list tool with no output schema, this description is fully sufficient: it states return fields, filter semantics, read-only nature, and exclusion of closed sessions. Nothing an agent needs to call it correctly is missing.

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 schema already documents server as 'Filter by server name' (100% coverage), the description adds crucial semantics: the parameter is optional, is a case-insensitive substring match, and omitting it lists all active sessions. This materially improves parameter understanding 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 opens with a specific verb and resource—'Lists currently active SSH sessions'—and enumerates the exact fields returned, distinguishing it from sibling session-mutation and listing tools. No ambiguity 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?

It clearly conveys that this is a read-only inspection tool and explains how to use the optional server filter, including the omit-to-list-all behavior. It does not name explicit alternative tools for mutation, but the read-only framing tells an agent when not to use it, so the usage context is solid.

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 so thoroughly: it discloses mutation, non-idempotency, persistence of cd/export changes, bash-style Unix interpretation, potential refusal by readonly/restricted servers, and default timeout. This gives the agent a clear safety and side-effect profile.

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

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

The description is dense but well-ordered: core purpose first, followed by side-effect warnings and operational constraints. The only slight redundancy is repeating the timeout default already present in the schema, but every other sentence adds valuable information.

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

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

The description covers purpose, prerequisites, side effects, shell behavior, security restrictions, and timeout, which is sufficient for invocation. It does not explain the return value or error format, and there is no output schema to compensate, so it is not fully complete.

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

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

Schema coverage is 100% and the schema documents all three parameters, so the baseline is 3. The description adds extra command-parameter semantics by explaining that commands reuse the session's persisted state and that cd/export mutate that state for later calls, which goes beyond the schema's terse 'Command to execute in the session.'

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 opens with a specific verb and resource: 'Runs one command inside an already-open session identified by its session ID.' It clearly distinguishes this from sibling one-shot tools by emphasizing the persisted session context, so an agent can identify what this tool is for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly establishes the required context: the session must already be open and is identified by a session ID, implying use after ssh_session_start and not as a standalone execution tool. It does not explicitly name alternatives or exclusions, but the context is strong enough to guide selection.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It openly states that the tool is stateful, side-effecting, may reuse pooled connections, keeps an open shell, preserves working directory/environment/history, and consumes a remote shell until ssh_session_close is called. This is thorough and accurate.

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?

Three dense, information-rich sentences with no redundancy. The core behavior is front-loaded, and every sentence adds value by covering statefulness, lifecycle, comparison to alternatives, and parameter semantics.

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?

Despite no output schema, the description gives the key return value (generated session ID), defines the lifecycle, and warns that the session consumes resources until closed. Sufficient context is provided for an agent to select and invoke the tool successfully.

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 parameters are already documented. The description adds meaningful context beyond the schema by explaining that 'server' refers to a named configured server and that 'name' is only a human label, which clarifies intent and prevents misuse.

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

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

The description clearly states a specific verb and resource: opens a new persistent interactive shell on a configured server and returns a session ID. It explicitly differentiates from one-shot ssh_execute, and the stateful, multi-call nature is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly conveys when to use this tool: when a persistent shell with preserved context across subsequent calls is needed, and contrasts it with ssh_execute. It could be slightly more explicit about when not to use it or when to choose other siblings, but the intended usage is strongly implied.

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 so thoroughly. It discloses that the tool mutates the destination, that delete true is destructive, that dryRun true is safe, that compression is on by default, that password auth requires sshpass, that it is blocked on readonly/restricted servers, and that the timeout defaults to 30000 ms.

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 dense but efficient, with the core purpose front-loaded and every subsequent sentence carrying operational or safety value. The Windows path warning is lengthy but essential, and no unnecessary fluff is present.

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 10-parameter tool with no annotations and no output schema, the description covers path semantics, defaults, destructive behavior, auth requirements, and blocking conditions comprehensively. The only notable gap is that it does not describe the return value or result output, which would normally be helpful given the absence of an output 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?

Although schema coverage is 100%, the description adds significant meaning beyond the schema: local:/remote: prefix semantics, Windows native path requirements and the MSYS2 conversion warning, the no-prefix push assumption, and functional details for delete, dryRun, compress, and timeout defaults.

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: synchronizes files or directories between local and remote using rsync over SSH on the named server. It clearly distinguishes this from one-way transfer siblings like ssh_upload and ssh_download by requiring local:/remote: prefixes and supporting bidirectional sync.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides strong usage context: both source and destination need prefixes, exactly one side must be local and the other remote, and a missing prefix assumes a push from local to remote. It also gives platform-specific path guidance and prerequisites like sshpass, though it does not explicitly name alternatives or when-not-to-use cases.

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 behavioral disclosure — and it delivers. It states the tool is read-only and does not modify remote state, and crucially reveals a non-obvious behavior: in follow mode (the default), output is written to server process stderr and the response only returns a session note, not content. It then tells the agent how to get content (set follow=false). This is exactly the kind of behavioral nuance a caller must know and could never infer from the schema alone.

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 purpose is front-loaded in the first sentence, and every sentence earns its place — purpose, safety claim, behavioral mode explanation, and defaults. The third sentence is a long, multi-clause run-on that packs several facts (streaming, stderr destination, session-note response, follow=false alternative, lines default) into one dense stretch. It is information-dense rather than bloated, but it could be restructured into clearer discrete sentences for easier parsing.

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 must explain return behavior — and it does, telling the agent that follow mode yields only a session note while follow=false returns the last N lines. Defaults are disclosed. Minor gaps remain: no mention of error behavior (unknown server, missing file), no clarification of whether grep applies in follow mode, and no detail on what the session note references. These are secondary to the core call-and-interpret cycle, which is well covered.

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 baseline is 3. The description adds significant value on top: it explains that `follow` changes the entire output behavior (session note vs. returned lines) and that `lines` defaults to 10. It also reinforces `server` as a named configuration entry and `file` as the log path. The description does not merely echo schema text; it explains the behavioral consequences of the key parameter, which lifts it above baseline.

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 and resource: 'Reads the tail of a remote log file on the named server, optionally filtered by a grep pattern.' This precisely states what the tool does and clearly differentiates it from siblings like ssh_execute, ssh_monitor, or ssh_db_query — none of which tail log files. An agent can identify this tool's 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 use case is clearly implied: tail a remote log file, with optional grep filtering. The description gives strong internal mode-selection guidance (set follow=false to capture content directly vs. follow=true for streaming). However, it never names alternative tools or states when NOT to use this tool, despite 35 siblings including monitoring-oriented tools (ssh_monitor, ssh_service_status, ssh_health_check) that an agent might confuse it with. The routing to siblings is left 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 provided, the description carries the full behavioral burden, and it does so thoroughly. It discloses that the operation is irreversible ('Closing is final and cannot be undone'), scoped to local state only, and that the server mode reports how many tunnels were closed.

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?

Three dense sentences convey the action, scope, parameter contract, error behavior, and irreversibility without any filler. The most important scoping 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?

For a two-parameter tool with no output schema and no annotations, the description is complete enough to invoke correctly: it explains what each parameter does, the exclusivity constraint, the error case, the local-only effect, and the destructive finality. An agent has sufficient information to decide when and how to call this 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?

Although the schema already describes both parameters, the description adds critical semantics beyond the schema: the exact-one requirement, the difference between single-tunnel and server-wide closing, and the error condition when neither is supplied. This meaningfully helps an agent choose and populate the right parameter.

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

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

The description names a specific action ('Tears down active SSH tunnels') and a clear resource ('active SSH tunnels created earlier'), and immediately clarifies scope by saying it affects only local tunnel state and not the remote host. This distinguishes the tool from related SSH tools like ssh_tunnel_create and ssh_session_close without ambiguity.

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 explicit parameter-selection rules: exactly one of tunnelId or server must be supplied, tunnelId targets one tunnel, server targets all tunnels for that server, and supplying neither raises an error. It provides clear operational context, though it does not explicitly name alternatives such as ssh_tunnel_list for discovering tunnel IDs.

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 behavioral disclosure burden. It clearly states the tunnel 'keeps running until closed' and that a tunnel ID is returned for later closure, which are important side-effect and lifecycle traits. It does not mention authentication requirements or failure modes, but the core persistent behavior is 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 concise: three sentences with no redundant wording. It front-loads the core action, then efficiently covers mode selection, required vs. optional parameters, defaults, and return value.

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

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

Given the lack of annotations and output schema, the description covers the essential invocation details: operation, parameter rules, default values, and return value. It is slightly incomplete by not referencing the sibling close/list tools or noting authentication prerequisites, but it is sufficient for correct basic invocation.

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

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

Although the schema already has 100% description coverage, the tool description adds significant semantic value beyond it: it explains how 'type' selects among local, remote, and dynamic modes, that localPort is always required, that remoteHost/remotePort are conditionally required, and that localHost defaults to 127.0.0.1. This helps an agent construct valid invocations.

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 ('Opens a new SSH connection') and names the exact resource ('port-forwarding or SOCKS proxy tunnel'), clearly distinguishing this from generic SSH execution tools. It also explains the tunnel lifecycle and return value, leaving no ambiguity 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?

The description gives clear context for when to use the tool: when a persistent SSH tunnel is needed. It explains the three tunnel types and parameter requirements per type, but it does not explicitly name alternative sibling tools or state when not to use this tool.

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 delivers important behavioral traits: it is read-only, does not create/modify/close anything, and only lists tunnels tracked by this process. It also specifies the exact data returned, though it does not cover potential side effects like error handling or resource limits, which are not critical for a simple list operation.

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 compact, well-structured set of three sentences. It leads with the core purpose, lists the output fields, states the read-only nature, and explains the parameter. Every sentence adds value with no 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?

For a list tool with one optional parameter, the description is complete: it identifies the resource, the filter, the output fields, and the read-only semantics. It doesn't mention pagination or output limits, but these are not essential for a simple listing operation and are not indicated by the presence of an output 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?

The schema already describes the 'server' parameter as a filter, but the description adds the nuance that it filters to one server and that omitting it lists all tunnels across servers. This clarifies the optional behavior beyond the schema's basic 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 clearly states the tool lists active SSH tunnels tracked by the process, enumerating the specific fields returned. It distinguishes itself from sibling tools like ssh_tunnel_create and ssh_tunnel_close by being a read-only listing 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 description implies when to use the tool (for inspecting active tunnels) and explicitly notes it is read-only, signaling not to use it for modifications. It does not name alternative tools directly, but the read-only statement and the presence of create/close siblings provide adequate context for an agent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly covers side effects: 'overwriting any existing remote file,' 'mutates remote state and is not idempotent beyond replacing the target,' 'creates no backup,' and the no-sudo limitation. It also discloses security-mode blocking. This is exemplary transparency for a mutation tool.

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

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

The description is largely efficient and front-loaded with the core action. However, there is mild redundancy: 'overwriting any existing remote file at that path' is restated by 'not idempotent beyond replacing the target.' Both convey the same overwrite behavior, so a sentence could be trimmed. Overall it remains compact 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?

For a three-parameter mutation tool with no output schema and no annotations, the description supplies all critical operational context: prerequisites, destination writability, overwrite behavior, backup absence, security-mode restriction, and sibling routing. No essential information an agent needs to call this tool correctly is missing.

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% but the descriptions are minimal (e.g., 'Local file path', 'Remote destination path'). The description adds meaningful semantics beyond that: localPath must reference an existing local file, remotePath must be writable by the configured SSH user, and the upload overwrites any existing remote file. This enriches the parameter meaning without overloading.

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+resource: 'Uploads one local file to a remote destination path over SFTP on the named server.' It clearly distinguishes itself from siblings like ssh_download (opposite direction) and ssh_sync ('For directory trees use ssh_sync instead'). An agent can understand exactly what this tool does without ambiguity.

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 explicitly names the alternative (ssh_sync) and the condition that selects it: 'For directory trees use ssh_sync instead.' It also provides concrete usage constraints: the local file must exist, the remote path must be writable by the SSH user, and the tool is blocked on readonly/restricted servers. This gives clear when-to-use and when-not-to-use guidance.

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