termalin-web

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

Annotations only signal possible mutation (readOnlyHint=false, destructiveHint=true); the description adds the crucial nuance that only SELECT/SHOW run unless allowWrites is set, and that writes require full-access keys. It also discloses the passwordless auth mechanism (sudo -u postgres, unix socket, etc.), that no password is stored, and the CSV/TSV return format — all beyond structured metadata.

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 carry the core purpose, auth model, safety default, and engine-specific behavior without fluff. The most important constraints (passwordless, read-only default) are front-loaded, and supporting details are compactly grouped.

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

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

With no output schema, the description wisely explains return formatting for SQL engines and gives a concrete MongoDB usage example. It is less explicit about redis-cli output formatting and does not discuss failure modes, but for a multi-engine query tool the coverage 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?

The input schema already covers 100% of parameters with useful descriptions, so the baseline is 3. The description adds extra semantics for the query parameter (MongoDB shell-expression example, SQL CSV/TSV output) and explains the default read-only behavior tied to allowWrites, which is not fully expressed in the schema itself.

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 ('Run a database query') with a clear resource (a chosen server's database engine) and immediately differentiates itself from generic shell/ssh tools by specifying it operates via each engine's client over the tunnel. The description also enumerates supported engines, so an agent can tell exactly what this 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?

Explains when to use it (when a database query is needed on a known host) and provides strong selection cues: no DB password needed, local trust, read-only by default, and MongoDB expression mode. It does not explicitly name sibling alternatives like ssh_exec for ad-hoc shell commands or data_tables for schema listing, so exclusion guidance is implicit rather than explicit.

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

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

Annotations already mark this as read-only, and the description adds meaningful behavioral context: the operation is passwordless and uses the same local-client path as data_query. This helps set accurate expectations about authentication and transport without contradicting the 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?

The description is a single front-loaded sentence with no filler. Every phrase earns its place: it names the operation, the resource, the transport, and the authentication behavior.

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 listing tool with full schema coverage and annotations, the description covers the essential purpose, transport, and auth context. It does not describe the return shape, but 'List the tables / collections / keys' makes the result type reasonably self-evident, and there is no 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description's 'tables / collections / keys' phrasing adds light engine-awareness to the enum, but it does not add substantive per-parameter 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 clearly states the action ('List') and the resource ('tables / collections / keys of a database'), which is specific enough to distinguish it from query, file, and SSH operations. However, it does not explicitly name or contrast any sibling tool, so it stops short of the strongest differentiation.

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

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

There is no explicit guidance on when to use this tool versus data_query or other siblings. The phrase 'same local-client path as data_query' signals a relationship but does not state a selection rule, alternatives, or exclusions.

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

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

Annotations already state readOnlyHint=true and idempotentHint=false, so the description doesn't need to re-cover safety. It adds valuable behavioral detail: 'Returns the password only; nothing is stored.' The description and annotations are consistent.

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

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

Two short sentences with zero filler. The main purpose and key behavioral guarantee are front-loaded, and there's no extraneous detail.

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 utility with annotations and no output schema, the description is complete: it states what the tool does, when to use it, what it returns, and the storage guarantee. 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 description coverage is 100%, and the single parameter length is already documented with default and range ('default 20, 8-128'). The description adds little beyond the schema, but for one simple parameter, that is acceptable.

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 precise verb ('Generate') and resource ('strong random password') and immediately explains the practical use case. The tool is clearly distinct from all siblings (hosts_list, sftp_list, etc.), so an agent can tell when to reach for it.

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

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

The description gives concrete contexts: 'handy when creating a user or setting a password on a server.' It doesn't explicitly say when not to use it or name an alternative, but given no sibling does anything similar, the usage context is strong enough.

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?

Annotations already ask readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral detail about what the tool returns and scopes the result set to Termalin reachable servers, which goes beyond the annotation.

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 concise sentences with no filler. The first sentence states the purpose, the second states the output and gives the follow-up usage. Every sentence carries essential 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?

Given no parameters, no output schema, and a low-complexity listing, the description is functionally complete enough: it covers purpose, scope, output fields, and the next command. Offline reachability and sorting are minor omitted details, but no are not necessary.

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?

There are zero parameters and schema coverage is 100%, so no additional parameter explanation is needed. The description does enough by explaining that the returned id is the relevant value for following commands.

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

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

The description states the action ('List') and the specific resource ('servers reachable through Termalin'), and even enumerates the returned fields (id, name, online status, default login user). It also positions the tool within its sibling set by referencing ssh_exec, so an agent can clearly distinguish it from sftp or password 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 a clear context: use it to discover servers reachable through the current tunnel agents and obtain the id needed for ssh_exec. It does not explicitly compare it to sftp_list or other alternatives, but the framing is clear enough.

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

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

The description adds useful behavioral context beyond the annotations: it runs keyless over Termalin's tunnel and returns name, directory flag, size, and modified time. The readOnlyHint annotation is consistent with the described read-only listing behavior.

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

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

The description is two crisp sentences with no filler. It front-loads the core operation and then adds only the high-value details of return fields, keyless auth, and tunnel behavior.

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 listing tool with no output schema, the description covers the important return fields, the access mechanism, and the required server context. The schema covers all parameter semantics and defaults, making the overall definition sufficient without describing every edge case.

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

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

Schema description coverage is 100%, so the schema already explains host, path, and username. The description adds no new parameter semantics beyond the general directory-listing context, which matches the baseline for fully documented schemas.

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: 'List a directory on one of your servers over SFTP.' It clearly distinguishes itself from sftp_read and sftp_write, which deal with file content rather than directory listings.

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: use this tool to list SFTP directories on servers, and the returned entry fields indicate what an agent can expect. It does not explicitly name alternatives or say when not to use it, but the scope is clear enough for siblings like sftp_read and sftp_write.

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

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

The readOnlyHint already signals safety, and the description adds useful behavior: files over 512 KB and binary files are refused, so the agent won't be surprised by failure. This goes beyond what annotations alone communicate.

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

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

The description is two sentences, front-loads the core action, and packs the critical limits and alternative into the second sentence without 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?

With no output schema, the description explains the return value ('return the contents') and covers the important edge cases. An agent has enough to correctly invoke 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?

Schema coverage is 100%, so all three parameters are already well documented. The description adds no additional param-level detail, which keeps it at the baseline 3.

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

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

The description states a specific verb and resource: read a text file over SFTP and return its contents. It clearly distinguishes the tool from siblings by noting it is for text files only and explicitly routing large/binary files to ssh_exec.

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 usage boundaries: use this tool for text files under 512 KB, and use ssh_exec for larger or binary files. It also provides concrete examples of how to handle excluded cases with sed/tail.

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

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

The description discloses overwrite semantics, UTF-8 encoding, a 512 KB cap, and the limitation against binary uploads. These go beyond the annotations and add meaningful behavioral context. The description agrees with the idempotentHint and destructiveHint annotations, so there is no contradiction.

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 short, focused sentences deliver purpose, behavior, and alternative guidance without any fluff. The most important 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 write operation with four documented parameters, no output schema, and no nested objects, the description covers the essential non-obvious details: overwrite behavior, encoding, size cap, and the binary-upload alternative. An agent has enough information 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 parameters are already well documented. The description adds useful value by clarifying that 'content' is written as UTF-8 and capped at 512 KB, which supplements the schema meaning rather than repeating it.

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: create or overwrite a text file over SFTP. It also naturally distinguishes itself from sftp_read and sftp_list by signaling the write direction, and from ssh_exec/scp by constraining scope to text files.

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 tells the agent when to use an alternative: 'for binary uploads use a terminal/scp instead.' It also implies the right conditions for use by mentioning text files, UTF-8 content, and a 512 KB limit.

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

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

The description reveals behavioral traits beyond the annotations: it returns combined output, requires no SSH key, and needs no open inbound port. These statements complement the destructiveHint and readOnlyHint annotations, adding context about how the command is transported and what output to expect.

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 compact sentences with no filler. The first sentence front-loads the verb, target, and output; the second adds critical transport context. Every phrase contributes to understanding the tool.

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

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

Given the full input schema, the destructive/read-only annotations, and the absence of an output schema, the description provides enough to invoke the tool correctly: what the command does, how output is returned, and the connection model. It does not mention exit-code behavior or timeout semantics, but those 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?

The schema already provides descriptions for all four properties (host, command, username, timeoutSeconds), so schema coverage is 100%. The tool description does not add new meaning about the parameters themselves; it only repeats the operation context. Thus baseline 3 is adequate.

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

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

The description states the specific verb and resource: 'Run a single shell command on one of your servers and return its combined output.' This clearly distinguishes the tool from siblings like sftp_read/write, which perform file operations rather than command execution. The transport detail further disambiguates the 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 gives clear context: this is for one-off shell commands on a server, executed keylessly over Termalin's tunnel with no SSH key or open inbound port. It does not explicitly mention sibling tools or say when not to use it, but the command-execution framing provides enough situational guidance.

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