termalin-web

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

Annotations mark destructiveHint=true and readOnlyHint=false, and the description reconciles this by explaining the default read-only posture plus the exact escape hatch (allowWrites, full-access keys). It also discloses the auth model (peer auth / unix socket, no password stored) and the return format (CSV/TSV with header), which annotations cannot convey.

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-loads the core action and mechanism, then layers default behavior and the MongoDB example. The parenthetical auth list is dense but earns its place; the description is a bit long but no sentence is pure 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?

No output schema exists, so the description carries the return-value burden and does so ('CSV/TSV with a header', MongoDB array expressions). Combined with the auth, default-write, and timeout disclosures, 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 value beyond the schema: a concrete MongoDB expression example, the sqlite database-as-file-path convention, and the fact that allowWrites is gated on full-access keys. Only the engine->auth-method mapping is implicit rather than spelled out per value.

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

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

States a specific verb+resource ('Run a database query on one of your servers') and immediately names the mechanism (engine's own client over a keyless tunnel). This clearly distinguishes it from ssh_exec (arbitrary commands) and data_tables (metadata), so an agent can route correctly without opening 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?

Gives strong operational context: read-only by default, writes only with allowWrites and full-access keys, and a warning that calls over ~90s get cut off so long jobs should run in background. It stops short of explicitly contrasting with ssh_exec/data_tables as alternatives, so it's clear-context but not full routing guidance.

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

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

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?

Adds substantial context beyond annotations: keyless auth over a tunnel, no inbound port needed, fresh shell per call (cd does not persist), ~90s hard cap, and the nohup background pattern. Annotations only flag destructive/non-idempotent; the description explains the operational envelope that an agent must respect.

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 tight sentences, front-loaded with what it does and its return shape, then constraints, then the long-job workaround. Every sentence 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?

Covers auth model, per-call isolation, timeout ceiling and long-job pattern, which is everything needed to invoke correctly. It does not spell out what 'combined output' looks like (stdout+stderr interleaved?) or exit-code handling, a minor gap for a tool with 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 coverage is 100%, so baseline is 3. Description reinforces host/command semantics and — importantly — the timeout guidance ('keep a call under about 90 seconds') that qualifies timeoutSeconds, adding meaning beyond the schema's own note.

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) and resource (a single shell command on one of your servers) plus behavioural scope: combined output and exit code. Distinguishable from siblings like sftp_read/write (file transfer) and data_query (structured queries).

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 the keyless tunnel model and points at hosts_list indirectly via the host parameter. It also says when to deviate: long jobs should be backgrounded and polled with later calls. No explicit exclusion of alternatives (e.g. running scripts vs one-liners), but the context is clear.

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