Termalin

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the description isn't burdened with that. It earns credit by adding scope the annotations can't convey: the lookback window (last seven days for cleared alerts) and the coverage caveat that only servers with metrics enabled appear.

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?

It leads with the answer to 'what does this return' before listing examples and caveats. The long parenthetical enumeration is dense but each example narrows the concept of an alert and earns its place; no sentence is 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 zero-parameter, no-output-schema tool the description supplies everything an agent needs: what is returned, the time window, the coverage limitation, and when to reach for it first. Nothing material is left open.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading or absent parameter guidance is present.

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 resource (server alerts) and enumerates exactly what qualifies as an alert — disk filling, memory/load pinned, failed service, restarting container, expiring certificate, offline server. That enumeration distinguishes it from sibling server_metrics, which returns metric series rather than problems.

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

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

It gives explicit entry-point guidance ('Start here when asked how the servers are doing'), which is strong usage context. It does not, however, name the alternative tool to use when the agent wants raw metrics or historical data, so it stops short of full when/when-not routing.

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?

Goes well beyond the annotations: it discloses the ~1 minute wait with longer jobs continuing asynchronously (visible in backup_list), that the call consumes the owner's storage quota, and that retention removes the oldest archive once the 'keep last' count is reached — a destructive side effect the annotations only flag generically. The prerequisite/error path is also described.

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 core action is front-loaded in the first clause, followed by timing, prerequisites, and retention — all information that earns its place. Minor waste in re-explaining what the 'label' parameter is for, which the schema already covers.

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 still explains what happens during and after the call (waits, or keeps running and appears in backup_list) and the failure mode when no backup job exists. Things like the returned job/archive identifier or behavior for an unknown host are unstated, but for a 3-param tool with full annotation coverage this is close to 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%, so all three parameters are already documented, including the same 'job defaults to the first' and 'label = why' hints. The description restates the label guidance rather than adding new meaning (format, length limits, behavior when job name doesn't match), so baseline 3 applies.

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

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

States a specific verb and resource ('Make an encrypted backup of one of the user's servers now') and names the mechanism ('through Termalin's backup job for that server'). It also implicitly distinguishes itself from backup_list by pointing there for long-running jobs, so an agent can separate it from the sibling list tool without opening schemas.

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 trigger ('Call it BEFORE a risky change — a migration, a config rewrite, a bulk delete') and a stated prerequisite (a backup job must exist in the Termalin cabinet, otherwise the tool explains how to add one). It also routes the agent to backup_list for jobs that exceed the wait window, which is the relevant alternative.

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 real context about what the call yields — per-backup run time, success flag, size, and storage location — which is exactly the kind of content annotations can't express. No pagination or volume limits are mentioned.

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, zero waste: sentence one defines scope and return contents, sentence two lists the triggering scenarios. Front-loaded and appropriately sized.

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

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

With no output schema, the description valuably enumerates returned fields (timing, success, size, storage location), covering what an agent needs to interpret results. There's no mention of how many recent archives are returned or whether large result sets are truncated, a minor gap for a list 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% with a single required 'host' parameter fully described as 'Server id or exact name from hosts_list'. The description adds no syntax or format guidance beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource: backup jobs and recent archives for one server, plus the fields returned (run time, success, size, storage location). It doesn't explicitly distinguish itself from sibling job_list or backup_create, which is the only thing keeping it from a 5.

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 two concrete situations: verifying a backup exists before a risky change and checking whether last night's backup succeeded. That's clear usage context, but it offers no exclusions or explicit pointer to siblings like job_status or backup_create.

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?

Goes well beyond the annotations by disclosing the passwordless auth path (peer auth via sudo -u postgres, unix-socket for MySQL, redis-cli, mongosh, sqlite3), the write gate and its key-permission requirement, and the practical ~90s network cutoff. Annotations only flag destructive/openWorld; the description explains what actually gets executed and under what constraints.

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

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

A single dense paragraph that is front-loaded with the core action, then auth mechanics, then the read-only default, then output format. Every clause carries information, though the engine-by-engine auth enumeration is slightly list-heavy for a description.

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 correctly compensates by stating the return shape per engine (CSV/TSV with header for SQL, array for the MongoDB example). With 7 parameters, two required, and full schema coverage, nothing an agent needs to invoke 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?

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it clarifies that MongoDB expects a shell expression (with a concrete example), that SQL engines return CSV/TSV with a header, and that allowWrites is gated on key scope. It stops short of documenting host, username, or database formats beyond the schema.

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

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

States a specific verb and resource ('Run a database query on one of your servers') and immediately distinguishes itself from the ssh_exec siblings by naming the mechanism it uses (the engine's own client over the keyless tunnel). An agent can tell this is DB-query execution, not generic shell access, 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?

Gives a clear default posture ('Read-only by default: only SELECT/SHOW-style statements run unless allowWrites is set') and the precondition for writes ('full-access keys only'). It does not explicitly name alternatives (e.g. use ssh_exec for non-DB commands or data_tables to discover tables first), so routing guidance is implied rather than spelled out.

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, non-destructive and openWorld, so the safety profile is covered. The description adds real context beyond that by specifying the exact fields returned and the supported engines (postgres, mysql, mariadb, sqlite). It omits auth/permission requirements and behavior on an unknown host or table.

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 sentences, front-loaded with the purpose and return contents before the usage instruction. The closing engine sentence is largely redundant with the schema enum, which is the only wasted clause.

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?

There is no output schema, so the description correctly carries the burden of explaining what comes back, and it does so thoroughly. Coverage of failure modes (bad host, missing table, insufficient permissions) is absent, but nothing essential to calling the 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 description coverage is 100%, so every parameter including the engine enum and the sqlite file-path note is already documented in the schema. The description's only parameter-relevant content is the engine list, which merely restates the enum. Baseline 3 is correct.

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

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

Uses a specific verb and resource ('Describe one table of a database') and enumerates exactly what is returned: columns, type, nullability, default value, primary key. This clearly separates it from data_tables (which lists tables) and data_query, though no sibling is named explicitly, so it stops short of a 5.

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 trigger: 'Call it before writing a query against a table you have not seen.' That ties the tool to the data_query workflow and states the condition that selects it. It does not state when not to use it (e.g. for a table you already know or for views), so it is not a full 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the operation is 'passwordless' and rides the same local-client path as data_query, which tells the agent it needs no credentials and shares connection semantics with a known sibling.

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

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

One compact sentence with the core action front-loaded and the qualifiers (passwordless, path) trailing. 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 read-only listing tool with rich annotations and full parameter coverage, and no output schema to explain, the description covers purpose, connection behavior, and scope. Only an explicit note on the shape of the returned listing would improve it.

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 per-parameter descriptions (host, engine enum with default, database incl. sqlite path, username default), so the schema carries the load. The description adds nothing parameter-specific beyond the notion of a single server, so baseline 3 applies.

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

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

States a specific verb (list) plus resource (tables/collections/keys of a database) and scopes it to 'one of your servers.' This clearly separates it from sibling read tools like data_query (which retrieves rows) and data_schema (which describes structure).

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 'over the same local-client path as data_query' implies this is a companion discovery step to querying, but it never explicitly says when to use this vs data_schema or gives a when-not condition. Usage is implied rather than stated.

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 cover readOnly/idempotent/non-destructive, and the description still adds substantial context the agent could not otherwise get: 'ip' is null until the Connector connects, 'ownerNote' is authoritative guidance the agent is told to follow, and 'policy' has three distinct levels (full / allowlist / readonly) with what each permits (no file writes under allowlist or readonly). For a discovery tool that gates all subsequent actions, that behavioral payload is exactly what matters.

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 and the long field enumeration is justified because there is no output schema to carry it. It reads as one dense paragraph rather than cleanly separated sentences, which makes it slightly harder to scan, but every clause carries real information and nothing is redundant.

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 fully carries the burden of explaining return values, and it does: id, name, online status, run-as user, last-seen, country, ip, ownerNote, and the policy enum. An agent has everything needed to call this and to act correctly on the result.

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 takes zero parameters, so the baseline is 4; the description correctly spends no space on inputs and instead explains how the returned id becomes the 'host' argument on other tools. That cross-tool note is useful but is not parameter semantics for this call.

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

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

States a specific verb and resource ("List the servers reachable through Termalin") and then enumerates exactly what is returned, so an agent knows this is the host-discovery entry point. It also positions itself relative to the other tools by saying the returned id is the 'host' argument they take, which implicitly separates it from alerts_list, job_list, and the ssh/sftp 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 closing sentence "Use the id (or the exact name) as 'host' in the other tools" makes clear this is the prerequisite call before ssh_exec, sftp_read, and friends. It does not add explicit when-not-to-use or exclusion language, but with no competing sibling serving the same purpose, the routing is unambiguous.

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, non-destructive, and openWorld, so the safety profile is fully covered structurally. The description adds the ordering trait ('newest first') and the returned fields, but says nothing about how many jobs 'recent' covers or any pagination limit.

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

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

A single efficient sentence front-loaded with the verb and resource, with the field list in a parenthetical rather than burying it. No filler, though the field enumeration is arguably schema-level 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?

With no output schema, the description compensates by naming the returned fields and their order, which is genuinely helpful. The remaining gap is the unbounded term 'recent', which gives no sense of result-set size or truncation behavior.

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 both parameters (host, username) including the default-user behavior are already documented in the schema. The description only confirms the server scope, adding no syntax or format meaning beyond that; baseline 3 applies.

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

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

The description states a specific verb and resource ('List the recent background jobs on a server') and even enumerates the fields returned (id, state, start time, command). It does not, however, distinguish itself from the sibling job_status, which an agent might reasonably confuse it with.

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 when-to-use guidance and no mention of the alternative job_status or job_start/job_stop, which operate on the same domain. The only usage signal is the implicit scope phrase 'on a server', leaving routing between job_* tools 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?

Annotations already cover the safety profile (destructive, non-idempotent, open-world), so the description's real value is the added behavioral detail: the job survives the call returning and connection closing, output is written to a log read via job_status, and the command runs from the login user's home directory. Auth/permission requirements and any concurrency limits are not mentioned.

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 tight sentences, front-loaded with the action and its immediate return, then usage, durability, and cwd. Every sentence carries distinct information with no repetition of the schema or annotations.

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 still names the return value (job id) and explains where the actual output lands. Combined with annotations and a fully documented schema, an agent has everything needed to invoke and follow up 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 description coverage is 100%, so baseline is 3, but the description adds genuinely new parameter-relevant context: the working directory for `command` is the login user's home, and the username choice must match the one used for job_status/job_stop (reinforcing the schema 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 (start), resource (shell command), execution mode (background on a server), and the immediate return (job id). An agent can distinguish it from ssh_exec (synchronous) and job_status (reads output) purely from the description.

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 a concrete when-to-use rule — anything over ~a minute, with examples (installs, builds, backups, migrations, downloads). It routes follow-up work to job_status but never explicitly names ssh_exec as the alternative for short commands, so the exclusion is only 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds substantive non-annotation detail by describing the return contract (running vs finished, exit code, start time, tail of output), which matters since there is 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?

A single front-loaded sentence with the action first and the payload of results following. No filler or repetition of the title.

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 usefully explains what a status check returns, and the schema fully covers all four inputs. It is close to complete; minor gaps remain around unknown-job behavior and output truncation limits, which the schema only partially covers.

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 job/host/lines/username are each documented in the schema. The description only restates "last lines of its output" for the lines parameter without adding format or truncation guidance beyond the schema; baseline 3 applies.

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

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

States a specific verb (Check) and resource (background job), and uniquely ties it to the job_start lifecycle. It also enumerates what a check yields (running/finished, exit code, start time, tail output), which no sibling (job_list, job_stop) claims.

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?

"Check a background job started with job_start" anchors the situation clearly, implying use for a specific known job id rather than enumerating jobs (job_list) or terminating one (job_stop). No explicit exclusions or named alternative, 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: the two-stage termination (polite request, then force after two seconds) and the no-op-on-finished-job behavior, which explains both destructiveness and idempotence concretely.

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

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

One sentence plus a parenthetical, front-loaded with the action and the origin tool, with zero redundant phrasing. Every clause (escalation timing, finished-job no-op) 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 3-parameter mutation tool with no output schema, the description covers origin, escalation semantics, and the no-op case, while annotations cover destructiveness and idempotence. It omits return/failure reporting, but that gap is minor given the schema is self-documenting.

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

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

Schema description coverage is 100%, and the schema itself explains all three parameters (job id from job_start, host id from hosts_list, optional username). The description adds no parameter-level detail, so the baseline 3 applies — the schema carries this dimension entirely.

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 (stop) plus resource (background job) and explicitly anchors it to the paired sibling job_start, distinguishing it from job_list/job_status. An agent can identify this as the termination counterpart to job_start without reading any schema.

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

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

It states the originating context ('started with job_start') and the edge-case condition ('does nothing if the job already finished'), so the agent knows it is safe to call blindly on an unknown job state. It stops short of naming explicit alternatives or when-not-to-use guidance, but the pairing makes usage unambiguous.

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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description still adds real behavior: data is sampled every minute, nothing is executed live, and the response shape changes based on whether `host` is supplied. It does not discuss auth requirements or rate limits, which keeps it short of a 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?

Front-loaded with what is returned, then the two parameter behaviors, then the usage guidance. The metric enumeration is long but functional, and every sentence carries information; only mild tightening is possible.

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 only two optional parameters, the description supplies everything needed: the returned fields, the two response modes, the default for `hours`, and the coverage limitation for servers without metrics enabled. Nothing an agent needs to call this 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%, so the baseline is 3, but the description goes further by explaining the semantic consequence of each parameter: omitting `host` yields one line per server, supplying it yields that server's full latest sample plus average and peak over `hours` (default 6). That is genuine added meaning beyond the schema's field-level 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?

States a specific verb+resource: reads the metrics Termalin's monitoring already collects (CPU, memory, disk, load, network, processes, services, containers, certificates) from the user's servers. It explicitly distinguishes itself from the closest sibling by saying to reach for it 'before reaching for ssh_exec', so an agent can route correctly without opening either 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?

Gives concrete when-to-use triggers ('how is the server doing', 'what happened at night') and names the alternative (ssh_exec) plus the boundary condition ('Covers servers with metrics switched on'). It also clarifies it does not run anything now, which rules out a plausible mis-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?

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely new behavioral context: it is keyless over the Termalin tunnel and shares the ssh_exec auth model, plus it enumerates the returned fields. What it omits is pagination or behavior on missing paths.

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 the action and resource, then return shape, then execution model. 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?

With no output schema present, the description compensates by enumerating the returned entry fields (name, is-directory, size, modified time) and explaining the credential model. 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 host, path, and username semantics (including defaults) are already fully documented in the schema. The description adds no parameter-level detail beyond that, making the baseline 3 correct.

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

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

States a specific verb (List), resource (a directory), and transport (over SFTP on one of your servers), which cleanly separates it from sftp_read/sftp_write file operations. It does not explicitly name a sibling to route against, so it falls short of the top score.

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

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

Usage is implied by the verb and by the trailing comparison to ssh_exec, but there is no explicit when-to-use statement, no exclusion of sftp_read for single files, and no guidance on choosing between hosts_list and this tool. Adequate but inferential.

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 readOnly, idempotent and non-destructive, so safety is covered; the description adds real behavioral constraints beyond that — the 512 KB ceiling and the refusal of binary files, which are enforced limits an agent must plan around. It does not discuss permission/escalation behavior when the tunnel user or username lacks read access, which is the main remaining 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, zero filler, with the core purpose and the size/content limit front-loaded before the alternative-tool routing. Nothing is padded.

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

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

For a 3-parameter read tool with full schema documentation and no output schema, the description supplies everything needed: what is returned (contents), the input limits, and where to go when those limits are hit. Read-only safety is already carried by annotations.

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 host, path and username are already documented with defaults and formats in the schema. The description adds no parameter-level detail (e.g. path normalization or username override semantics), so the baseline 3 applies.

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

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

Specific verb+resource ('Read a text file ... over SFTP and return its contents'), plus an explicit scope boundary (text only, under 512 KB) that separates it from generic exec tools. An agent can distinguish it from ssh_exec and sftp_list without opening any schema.

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

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

States the condition that disqualifies this tool (binary or >512 KB files) and names the alternative to use instead (ssh_exec with sed/tail). This is explicit when-not plus a named alternative, not 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the overwrite risk is covered structurally. The description still adds real value beyond them: the 512 KB cap, the UTF-8 encoding requirement, and the fact that an existing file is overwritten rather than appended.

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 zero filler; the core action leads and the size cap plus binary-upload fallback follow as constraints. 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 mutation tool with no output schema, the description covers the key call-time facts: encoding, size limit, overwrite behavior, and the alternative for binary. It omits any note on required permissions or failure modes, which is a minor gap given the annotations already flag destructiveness.

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

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

Schema description coverage is 100%, so host/path/content/username are already documented; the description only restates the UTF-8 nature of 'content'. It adds the 512 KB size ceiling, which is useful but not parameter syntax or format detail. Baseline 3 is appropriate.

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

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

States a specific verb (create or overwrite), resource (text file), and transport (SFTP on one of your servers). An agent can immediately separate this from sftp_read, sftp_list, and ssh_exec among the 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?

Explicitly routes binary uploads elsewhere ('for binary uploads use a terminal/scp instead'), which is a genuine when-not condition with a named alternative. It doesn't address other plausible confusions (e.g. vs. ssh_exec for writing files), so it stops short of full coverage.

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 cover safety profile (destructive, openWorld, non-idempotent), and the description adds traits annotations cannot express: keyless tunnel with no inbound port, a fresh shell per call so 'cd does not persist — chain with &&', and the network-enforced ~90s cutoff. These are exactly the behavioral facts an agent needs to call it correctly.

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 tight sentences, front-loaded with what the tool does and what it returns before moving to caveats and escalation path. No sentence is filler; each carries a distinct constraint or routing hint.

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, but the description names the return values (combined output and exit code). Combined with the timeout guidance, shell-persistence caveat, and long-job escalation path, nothing an agent needs to invoke this 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%, so the baseline is 3, but the description adds real semantic value for the 'command' parameter: the fresh-shell/no-persistent-cd rule and the ~90s ceiling that makes timeoutSeconds meaningful. The 'host' and 'username' parameters get no comparable treatment, keeping it short of a 5.

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 single shell command on one of your servers') plus the return value ('combined output and exit code'). The word 'single' implicitly distinguishes it from the sibling ssh_exec_many.

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?

Explicitly routes long-running work away from this tool: 'for anything longer (installs, builds, backups) use job_start and check on it with job_status.' It also names the concrete threshold (~90 seconds) that selects the alternative, leaving no inference to the 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?

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is carried structurally. The description adds genuinely new behavior: a 10-server cap and a 90-second limit inherited from ssh_exec. Minor tension: it advertises a 90-second ceiling while the schema caps per-server timeout at 80 (default 60), leaving the relationship between the two limits unaddressed.

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: what it does, when to prefer it over the per-server alternative, and the two operating limits. The purpose is front-loaded with zero preamble.

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, open-world batch tool with no output schema, the description covers the return content (per-server output and exit code), the fan-out limit, and the time bound. The only loose end is the unexplained gap between the stated 90-second limit and the schema's 80-second per-server maximum.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the host cap (up to 10) and the time limit, but adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('run the same shell command on several servers') plus the return payload (each server's output and exit code). It is clearly distinguished from its sibling ssh_exec by being the multi-host variant, so an agent can route between them without opening either 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?

Gives concrete when-to-use context (compare or check a fleet — disk space, versions, service state) and contrasts it with the one-call-per-server alternative. It does not state when NOT to use it or name ssh_exec explicitly as the single-host fallback, so it stops short of the top band.

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?

Beyond the annotations, the description discloses important behavior: nothing is exposed to the internet, no port is opened, only private addresses are accepted, and the returned open_url signs the owner in to Termalin. It also explains the session-gated nature of the generated URL and the account limit on internal sites.

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 action and then covers returns, caveats, and limits. It is longer than ideal but most sentences carry unique operational value, with only mild redundancy around access and sharing 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?

There is no output schema, but the description explains the return fields (id, open_url, url) and how to use open_url. It also covers the private-address constraint, session behavior, and the account limit, leaving an agent with enough context to invoke and follow up 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 description coverage is 100%, so the parameters are already well documented. The description adds useful semantic context that only private addresses are accepted and that the server is the one whose Connector reaches the site, though it does not discuss https_inside beyond what the schema 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 uses a specific verb and resource: it puts an internal web service into the owner's Termalin cabinet as an internal site. It clearly distinguishes this from opening, reading, or sharing the site, and names web_link_delete for removal when the limit is reached.

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 states the precise use case: a dashboard, admin panel, or app reachable only inside the server's network. It also gives exclusions and alternatives, noting that this tool does not open/read the site, cannot grant others access, and that removal is handled via web_link_delete.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description still adds real value beyond them: the address stops working immediately, the effect extends to everyone the owner shared it with, and the underlying server service is untouched. It does not state whether removal is recoverable or what authorization is required, which keeps it at 4.

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: the action first, then the blast radius, then the scope boundary. Every clause carries information an agent would otherwise have to guess.

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 tool with full annotation coverage and no output schema, the description supplies essentially everything needed to call it safely. The only missing piece is whether the deletion is reversible or how to restore a removed link.

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% for the single `id` parameter, which already states it comes from web_link_list or web_link_create. The description reinforces the source but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb ("Remove") and resource ("an internal site from the owner's Termalin cabinet") and pins the identifier to its origin (from web_link_list). An agent can distinguish this from web_link_create and web_link_list without opening any schema.

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

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

Usage context is clear: use it on an id obtained from web_link_list, and it removes the link rather than the server service, which excludes a plausible misreading. There is no explicit when-not guidance or named alternative for adjacent tasks (e.g., recreating or editing a link), 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?

Annotations already declare read-only/idempotent/non-destructive, and the description adds genuinely non-obvious behavior: the result set is scoped to servers the caller can reach, and raw url links fail without an authenticated Termalin session even for the owner. It does not cover pagination, result limits, or what an empty response means.

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, front-loaded with the resource and its fields, then the practical instruction about open_url. The opening field enumeration is dense and slightly list-like, but every clause carries 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?

No output schema exists, and the description compensates by naming each returned field and explaining the open_url vs url distinction, which is the main thing an agent could get wrong. Missing only operational detail such as ordering, pagination, or behavior when no sites exist.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description instead spends its words on return-field semantics (who added the link, share count), which is a reasonable use of the space.

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?

It names the specific resource (internal sites in the owner's Termalin cabinet, restricted to reachable servers) and enumerates the returned fields, so an agent knows exactly what comes back. The listing verb is only implied by the phrasing and the annotation title rather than stated in the description, and siblings like web_link_create/web_link_delete are not referenced.

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

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

It gives downstream usage advice — hand the user open_url rather than url — but never states when to call this versus web_link_create/web_link_delete, nor any prerequisites or exclusions. Usage is implied by the tool name and the field list rather than spelled out.

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