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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond that: the tool is passwordless, uses the same local-client path as data_query, and is engine-agnostic by listing tables, collections, or keys. 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?

The description is a single, compact sentence with no filler. The core action is front-loaded, and the appended context about passwordless access and the local-client path is relevant. Every clause earns its place.

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

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

For a 4-parameter listing tool with full schema coverage and rich read-only annotations, the description is nearly complete. It conveys the connection method, the conceptual return value, and the cross-engine scope. It does not specify exact output shape or error behavior, but that is largely implicit for a list operation.

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

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

Schema description coverage is 100%, with all four parameters already documented meaningfully in the input schema. The description adds no additional parameter-level detail, so it does not need to compensate for schema gaps. It stays at the baseline because it offers no extra semantic value for 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 states a clear verb and resource: 'List the tables / collections / keys of a database on one of your servers.' This makes the tool's function obvious. It does not explicitly contrast with sibling tools like data_query, though the phrase 'same local-client path as data_query' references a sibling without stating the differentiator.

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 it: when a listing of database tables/collections/keys is needed. It provides context about how access occurs ('passwordless, over the same local-client path as data_query'), but it does not explicitly state when to prefer this over alternatives such as data_query or sftp_list.

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 non-destructiveikuha; the description adds valuable behavioral context by stating that the password is returned but not stored. This clarifies side effects and privacy expectations beyond the schema.

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 that front-load the purpose and include only relevant behavioral and usage context. No wasted words.

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

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

For a single-parameter tool with safety annotations and no output schema, the description covers purpose, use case, return behavior, and side-effect absence. It does not explain what 'password' quality guarantees are (e.g., character classes), but the schema and annotations make the tool usable without that.

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 documents the only parameter (length) with default and range, so coverage is 100%. The description adds no parameter-specific meaning, but none is needed.

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, specific action—generate a strong random password—and its intended use cases. It naturally distinguishes itself from the sibling tools, which are all unrelated data and server operations.

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

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

The description gives a concrete usage context: 'handy when creating a user or setting a password on a server.' It doesn't explicitly name alternatives or exclusions, but given the sibling list, no reasonable alternative overlaps with 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by specifying the return fields (id, name, online status, default login user) and the connection to ssh_exec, which is useful given no output schema.

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 only two sentences, tightly packed with relevant information: what is listed, what fields are returned, and how to use the output. Every sentence earns its place and there is no redundant 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 zero-parameter, read-only listing tool, the description covers the essential context: the scope of servers, the returned fields, and the follow-up action (ssh_exec with the id). No output schema exists, so the explicit return-field listing completes the picture.

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

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

The tool has zero parameters and the schema is empty with 100% coverage, so there are no parameter semantics to document. Per the baseline for zero-parameter tools, a score of 4 is appropriate; the description cannot add parameter meaning where none exists.

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 starts with a specific verb and resource: 'List the servers reachable through Termalin.' It also states the exact fields returned and connects to the sibling ssh_exec tool via 'Use the id with ssh_exec,' making its role distinct from the other 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 clearly implies when to use this tool: when you need to discover reachable servers and obtain an id for ssh_exec. It does not explicitly state exclusions or alternative list tools, but the context is clear enough for an agent to select it appropriately.

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 establish readOnly, idempotent, and non-destructive behavior, so the description adds value by disclosing that it runs keyless over the tunnel and by explaining the returned entry metadata. This is meaningful beyond what the annotations and schema provide.

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: the first states the core action, and the second adds output shape and the keyless tunnel context. Every sentence earns its place, with no filler or redundant restatement of 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 simple list operation, the description plus schema covers required inputs, return fields, and connection/auth behavior. There is no output schema, but the description compensates by enumerating the returned entry properties. Error or permission edge cases are not mentioned, but they are not essential for selecting and invoking 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?

Schema description coverage is 100%, so the schema already documents host, path, and username including defaults. The description does not add parameter-level meaning beyond the schema, which warrants the baseline score of 3.

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

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

The description states a specific action ('List a directory') on a specific resource ('one of your servers over SFTP'), and it spells out the returned fields: name, directory flag, size, and modified time. This clearly differentiates it from siblings like sftp_read and sftp_write.

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 useful selection context by noting it is keyless over Termalin's tunnel and explicitly comparing it to ssh_exec. It does not state hard exclusions or decision rules versus sftp_read/sftp_write, but the listing behavior and return format make the intended use clear.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond those annotations: the 512 KB ceiling and refusal of binary files, which are the likely runtime failure modes. It does not describe error behavior for missing files, but that is a minor gap.

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

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

Two sentences with zero waste: the action is front-loaded, and the hard constraint plus workaround follow immediately. Every clause earns its place; there is no repetition of schema or annotation 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?

With no output schema, the description properly discloses the return value ('return its contents') and the critical constraints. For a simple read tool whose safety profile and parameters are already documented, this is nearly complete; only minor omissions like encoding or failure behavior prevent 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 description coverage is 100% — host ('Server id from hosts_list'), path ('Absolute or home-relative file path'), and username ('Login user...defaults') each carry meaning. The description adds no parameter-level detail beyond implying path points to a text file. Baseline 3 is correct when the schema does the heavy lifting.

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 ('Read'), a resource ('text file from one of your servers over SFTP'), and the result ('return its contents'). The 512 KB / binary-file refusal distinctly separates it from siblings like sftp_write, sftp_list, and especially ssh_exec without needing to inspect any schema. The title 'Read a file' is consistent and adds nothing contradictory.

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?

Gives an explicit when-not-to-use condition ('Files over 512 KB or non-text (binary) files are refused') and names the alternative with concrete command examples ('use ssh_exec (e.g. sed/tail)'). An agent can route correctly without 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?

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.