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

With no annotations, the description carries the full burden and does disclose non-schema behavior: noninteractive execution, preservation of existing config files, and the fact that docker/containerd upgrades restart remnanode (clients reconnect). It stops short of covering failure-handling semantics, permissions, or what the response contains.

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

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

Four compact sentences, front-loaded with the core action and safe to skim; each sentence adds a distinct fact (mode, docker risk, reboot, batching). Minor overlap with schema defaults keeps it from a 5.

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 an 11-parameter tool with no output schema and no annotations, the description gives a solid high-level picture of the operation, its disruptive side effects, and the reboot follow-up. The dry-run/planHash two-phase workflow and the shape of results are only touched on, leaving a small gap.

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 11 parameters are already documented in the schema; the description's mentions of batch default and the docker warning merely echo what the schema says. 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+resource ("Install pending apt updates on hosts") and immediately qualifies the operating mode (noninteractive, keeps existing config files), so an agent knows exactly what operation this performs. It does not explicitly distinguish itself from neighbors like updates_policy or remnanode_update, 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?

Usage context is only implied: the dry-run-then-apply flow, the docker/containerd warning, and the optional reboot tell the agent roughly when to reach for this, but no alternative tool is named and there is no explicit when-not guidance. Adequate but leaves routing to inference.

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

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

No annotations exist, so the description carries the full behavioral burden, and it does disclose one non-obvious hazard: deleting while the agent runs causes the card to be recreated. However, it omits that calls default to a safe dry run, that apply requires a one-shot planHash that is invalidated if targets change, and whether it fails on ambiguous name matches — all of which the schema states but the description does not reinforce.

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 rename/delete scope and target resolution front-loaded before the operational caveat. Nothing could be cut without losing information.

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

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

For a 5-parameter, destructive tool with no annotations and no output schema, the description covers purpose and one major hazard but leaves the dry-run/apply safety model, ambiguity handling, and post-call state entirely to the schema. Adequate but clearly incomplete for a mutation 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 80%, so the baseline is 3. The description adds only the parenthetical clarifying that "host" may be a tailnet name or IP, a modest clarification over the schema's "exact card name or host", and gives no semantics for apply/remove/planHash beyond what the schema already documents.

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 pair of verbs (rename or delete) on a specific resource (Beszel card) and defines how the target is located (exact name or host / tailnet name / IP). It is distinguishable from listing tools like beszel_systems, though it never names a sibling explicitly.

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 operational precondition for the destructive path ("Delete only after the agent on that machine is stopped, or it recreates the card"), which is real when-not guidance. It stops short of naming alternatives or telling the agent to enumerate candidates via beszel_systems before calling with an exact-match locator, and it defers dry-run guidance entirely to the schema.

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

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

No annotations are provided, so the description carries the full behavioral burden. It never states that this is a read-only operation, whether it hits the hub directly, whether it paginates, or what the return payload shape is beyond three field names.

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 compact sentence with no filler; the resource is front-loaded and the rationale follows. The em-dash aside about duplicates/removed nodes is slightly tangential but does not bloat the definition.

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 read tool with no annotations and no output schema, the description covers what a card contains but leaves the filter input and the read-only nature undocumented. Adequate, but with clear gaps an agent would need to guess around.

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 0% for the single 'filter' parameter, and the description never mentions it, so its matching semantics (substring, exact name, host?) are entirely unexplained. The field list describes return data, not the input parameter.

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

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

The description identifies the resource (Beszel hub 'systems'/'cards') and enumerates exposed fields (name, host, status), but omits an explicit verb such as 'list' or 'retrieve'. It is distinguishable from beszel_system_edit only by inference, not by any stated contrast.

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 through a narrow scenario: finding duplicate cards from a newly created agent and stale cards of removed nodes. There is no guidance on when to prefer this over siblings like beszel_system_edit, nor any exclusion or filtering advice.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the script path, the cron cadence it bypasses, and that entry counts are shown afterwards, but it is silent on the two-phase dry-run/apply mutation implications, host-wide side effects, and any permission requirements -- gaps the schema partly covers but the description should flag.

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 sentence with the action front-loaded and only a brief parenthetical for context. Efficient and readable, though the parenthetical interrupts the main clause slightly.

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 6-parameter fleet-wide mutation tool with no annotations and no output schema, one sentence is thin. It covers what and the return summary but leaves the dry-run-then-apply workflow and mutation safety implied by the schema rather than spelled out in prose.

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 six parameters (apply, batch, target, planHash, continueOnError, skipUnreachable) are already documented in the schema. The description adds no parameter-level meaning, 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?

States a specific verb and resource -- refreshing ipset blacklists -- and even names the underlying script and its normal cron trigger, which lets an agent distinguish this from ufw_rule or other firewall siblings. However it never explicitly contrasts itself against those 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 parenthetical '(normally run by /etc/cron.d/ufw-blacklist every 2 h)' implies this is a manual out-of-band refresh, which hints at when to reach for it. But there is no explicit when-to-use vs alternatives guidance and no stated prerequisites.

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

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

With no annotations, the description carries full burden. It usefully discloses the underlying command, the minDays skip rule, the port-80 precondition, and the restart consequence ('xray loads the new certificate'). However, it omits the safety-critical fact that the default is a dry run requiring a planHash to actually apply, and says nothing about SSH/permission requirements or failure semantics.

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

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

Four sentences, front-loaded with the action and mechanism, and the embedded command is genuinely useful rather than padding. Slightly dense but every clause conveys operationally relevant information.

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

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

For a nine-parameter mutation tool with no annotations and no output schema, the description covers purpose, precondition, skip logic, and the restart side effect. It leaves the dry-run/apply two-phase workflow to the schema, which documents it fully, so the remaining gap is minor.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters. The description adds only a restatement of minDays/force behavior and nothing about target, batch, or planHash beyond what the schema states, 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 (renew) and resource (remnanode TLS certificate), plus the exact mechanism (docker certbot via vps-edge-run.sh). No sibling tool competes for this function, so the agent can identify it immediately.

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

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

Provides concrete preconditions ('Port 80 must be publicly open') and the condition under which work is skipped ('more than minDays left unless force'). It does not name an alternative or exclusion, but no sibling overlaps, so the guidance is clear context without exclusions.

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

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

With no annotations, the description carries the full burden and does so well: it discloses backups to /root/mia-backup, that stock OS cron files are left alone, that the command itself is unchanged, that a logrotate error rolls the rotation file back, and the dry-run/planHash gating. This is unusually rich disclosure of side effects and reversibility for a mutation tool.

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

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

Purpose is front-loaded in sentence one, and the paragraph is dense with decision-relevant facts rather than filler. It is long and mixes fine-grained logrotate config detail (weekly, 8 copies, compress, copytruncate) that is arguably not needed for correct invocation, keeping it just under a 5.

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 six-parameter mutation tool with no annotations and no output schema, the description covers what changes, what is preserved, backup location, rollback behavior, and rollout hygiene. Nothing an agent needs in order to call this safely 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 apply/planHash/target/batch/continueOnError/skipUnreachable are all documented in the schema itself. The description adds only indirect hints ('Roll out a few hosts at a time' gestures at batch, 'a pipe into logger stays in syslog' at line handling) but no new parameter syntax or semantics, which matches the baseline 3 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?

The first sentence states a specific verb+resource with measurable outcome ('make every cron job write its output to a log and rotate those logs'), and later sentences clarify the job-vs-logrotate relationship and the fleet_schedule integration. An agent can distinguish this from siblings like fleet_schedule or host_file_edit 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?

It gives real operational guidance ('Roll out a few hosts at a time and look at fleet_schedule in between') and describes how existing lines are treated, so the agent knows the intended change process. It stops short of naming when NOT to use this (e.g. vs. host_file_edit for manual cron edits), so no explicit alternative 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?

With no annotations, the description carries the full disclosure burden and does much of it: it names exactly what gets removed, explicitly guarantees volumes are never touched, and signals a dry-run/plan workflow. It does not mention irreversibility, permission requirements, or the planHash single-use constraint, but the destructive-scope disclosure is solid.

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 tight sentences with zero filler. The action scope is front-loaded, followed by the dry-run behavior, so an agent reads the key facts first.

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

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

For a destructive multi-host mutation with no annotations and no output schema, the description covers what is deleted, what is protected, and the dry-run entry point. Remaining gaps (permissions, irreversibility, rollout behavior) are partially covered by the detailed schema, leaving it nearly 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 88%, so the schema already documents nearly all parameters, including apply, planHash, batch, and target semantics. The description only hints at journalSize ('journald vacuum to a size') and the dockerImages scope ('never volumes'). Baseline 3 is appropriate 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 (free) and resource (disk space) and enumerates the exact cleanup categories: apt cache, journald vacuum, unused docker images/build cache, rotated logs. The parenthetical '(never volumes)' sharpens the scope. It does not explicitly differentiate from siblings, but the specificity makes its function unambiguous.

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

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

The closing sentence implies a dry-run-first workflow ('The dry run shows what takes space now'), which hints at how to start. However, it never states when to prefer this over alternatives like host_exec or host_docker, nor any prerequisites. Usage 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?

With no annotations, the description carries the full burden and does well: it discloses the dry-run default, that the plan shows each record before and after, that records are read back after apply, the one-A-record-per-name invariant, and that planHash is single-use and invalidated by target state changes. It omits auth/permission requirements and any rate or concurrency behavior.

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

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

A single dense sentence front-loads the tool's identity and per-mode semantics, then closes with the plan/apply/read-back lifecycle. Every clause carries information, though the run-on density would benefit from light structural separation.

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 high-risk mutation tool with nested objects, no annotations and no output schema, the description covers the workflow, safety gate (planHash), and return behavior adequately. Missing permission/precondition detail keeps it short of 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 description coverage is only 40%, and the description compensates by explaining the three array/object parameters (set = name→IP create-or-update, move = every A record on one IP to another, remove = by name or by IP) plus the apply/planHash relationship already documented in the schema. The proxied flag and the set-item structure are left to the schema, so it is not fully exhaustive.

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

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

States a concrete verb (change A records in Cloudflare) and enumerates the three distinct sub-operations - set, move, remove - with their exact semantics. An agent can distinguish each mode from the sibling read-only tool dns_records 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?

Clear operational context: dry run is the default and apply requires a planHash from the very same call, with guidance that the plan is refused if targets changed. It does not, however, name an alternative sibling (e.g. dns_records for inspection) or state when this tool should be preferred over one.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the auth dependency (CLOUDFLARE_API_TOKEN) and an important scope trait — that the IP search spans all zones rather than one — which is genuinely useful. It says nothing about result limits, pagination, or how many zones/records are walked, so for an unannotated read tool the behavioral picture is only partially drawn.

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 that keeps the resource first and the query modes second, with a compact example. Zero filler, though the em-dash construction is slightly compressed and the implied verb ('list/find') never appears explicitly.

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-param, no-output-schema, no-annotation tool the description covers the essentials: resource, auth, the two query modes, and cross-zone scope. Missing is anything about return shape (list of records), pagination/limits, and interaction between 'name' and 'ip' when both are supplied, which an agent needs to invoke it confidently.

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 67%, so the schema already explains 'ip' and 'name'; the description mainly restates 'by name' and 'record that points at an IP'. Its real added value is the 'across all zones' scope note for the IP query, which the schema's one-line 'every record with this content' does not convey. The 'type' param and its 'any' default go unaddressed in both places.

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 the resource (DNS records in Cloudflare) and specifies the two query modes — resolving a name, or finding every record pointing at an IP across all zones. That is a clear, retrievable purpose an agent can act on. It does not, however, explicitly distinguish itself from the sibling dns_change, which mutates DNS records, so sibling differentiation relies on inference.

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

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

The two query modes (by name / by IP) are stated with a concrete example ('everything still on an old ingress address'), which implies when to reach for the IP mode. There is no explicit when-not guidance and no named alternative for modification (dns_change) if the agent actually wants to change rather than read.

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

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

With no annotations, the description carries the full behavioral burden, yet it only states the purpose. It doesn't disclose that this mutates firewall/ban state, that it defaults to a dry run requiring apply/planHash, or any permission or failure behavior; the dry-run mechanism is only visible in 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?

A single front-loaded sentence: verb and resource lead, scope follows, and the motivating example closes without waste. Compact and easy to scan, though the trailing example is optional.

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 5-parameter mutation tool with no annotations and no output schema, the description covers only purpose and a hint of context. The schema carries the critical dry-run/planHash mechanics, but behavioral facts an agent needs (state changes, error cases, whether the ban must exist) are absent.

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

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

Schema description coverage is a middling 60%, with ip and jail carrying only patterns and no prose. The description partially compensates by clarifying the jail parameter ('all jails, or one') and the host targeting ('on hosts'), but says nothing about apply/planHash/target beyond what the schema already documents.

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 (unban), resource (an IP in fail2ban), and scope (all jails, or one) applied across hosts. An agent can tell exactly what this does, and the parenthetical disambiguates the jail scoping rather than leaving it to the schema alone.

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 supplies a clear use context — 'after locking yourself out or a false positive' — which frames when an agent should reach for this tool. It does not name explicit exclusions or alternatives (e.g. ban-side tools), so it stops short of 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?

With no annotations, the description carries the full burden. It usefully discloses that findings carry stable codes and that policy.skip in fleet.yaml mutes them, plus the 'as the nodes run now' baseline posture. However it does not state read-only/safety expectations, auth requirements, or cost/runtime characteristics of such a broad audit.

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 is one massive run-on sentence cramming dozens of checks into parenthetical lists. Purpose is front-loaded in the first clause, but the rest is dense enumeration that is hard to scan and would benefit from structure.

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 complex fleet-wide tool with no output schema and no annotations, the description covers scope and the muting mechanism reasonably well, but omits what a run returns, how findings are shaped beyond codes, and safety/pacing expectations. Adequate but with clear gaps.

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

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

Schema coverage is 67%, so the schema already documents code, target, and minSeverity with their formats. The description adds a little (e.g., code prefixes relate to findings) but no syntax beyond the schema, so the 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?

The description opens with a specific verb (audit) and resource (hosts) against a named baseline, and enumerates the concrete checks, which distinguishes it from narrower siblings like host_inspect or tuning_status. It is clear what it does, though the wall-of-text enumeration makes the scope harder to parse than it needs to be.

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 what is audited but never says when to reach for this tool versus host_inspect, fleet_status, or the many individual host_* checks, nor any prerequisites or exclusions. Usage is only inferable from the scope listing.

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

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

With no annotations, the description carries the full burden. It discloses that live:true probes the host and that journal entries are appended alongside the diff, which is useful, but says nothing about permissions, cost/latency of live probing, or result shape. Adequate but incomplete for an annotation-free tool.

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

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

Two sentences, purpose front-loaded, no filler. The nested parentheses around `since` and `live:true` make it slightly dense to parse but nothing is wasted.

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

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

With no output schema and no annotations, the description must cover behavior and returns. It conveys the conceptual output (diff plus journal) but omits output format, volume expectations, and the safety/cost profile of probing hosts, leaving gaps for a zero-required-param reporting tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the `since` semantics ('first one after since') and the live:true meaning, but this largely duplicates the schema's own parameter descriptions rather than adding format or edge-case detail.

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

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

The opening clause 'What changed on hosts: diff of recorded snapshots' names the resource and the mechanism precisely, and the journal addendum clarifies the combined report nature. It implies but never explicitly names the siblings it overlaps with (snapshots_list, journal_list), 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?

It enumerates the operating modes (latest vs previous, vs the first snapshot after `since`, vs the live host) and states when live:true is warranted ('catches changes made by hand since'). No explicit when-not-to-use or named alternative is given, keeping it below 5.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the data sources (local tailscale status, Remnawave panel) and the shape of the results, which is genuinely useful context. However, it never states that the operation is read-only, whether it writes the 'ready YAML' to disk, or what permissions/network access it needs – meaningful gaps for a zero-annotation tool.

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

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

A single front-loaded sentence with the verb and sources up front and a colon-delimited list of outputs. Dense but every clause carries information; no filler or restatement of the name.

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 must convey return content, and it does so by enumerating the three result categories. Combined with the named data sources, an agent has enough to call it and interpret results; only the read-only/write-side-effect question remains unanswered.

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 no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter information is missing or misleading.

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 ('cross-check') and concrete resources: the inventory, the tailnet via local `tailscale status`, and the Remnawave panel. It also enumerates what it surfaces (missing nodes with ready YAML, offline/unknown hosts, panel node state), so the agent knows this is a reconciliation/discovery operation. It never names or contrasts with the closest siblings (fleet_audit, fleet_status, tailnet_devices), so it falls 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?

Usage is implied by the cross-check framing – you'd call this when inventory and reality may have drifted apart – but there is no explicit when-to-use, when-not-to-use, or alternative (e.g. fleet_audit vs this). The agent must infer the trigger condition from the verb alone.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that the dry run preserves layout and comments and refuses an unloadable result, and that apply creates a backup in the state directory and refuses if the file changed since the plan (optimistic-concurrency guard). It does not mention permissions or the exact failure surface, but the safety and workflow profile is unusually complete for a mutation tool.

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

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

Two dense sentences, front-loaded with purpose then behavior. No filler, though the second sentence is long and packs the dry-run/apply mechanics tightly.

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 17-parameter mutation tool with no annotations and no output schema, the description supplies the missing behavioral layer (dry run vs apply, backup, conflict refusal, comment preservation) while the schema covers parameter detail. An agent has what it needs to call it correctly, though explicit alternative routing is absent.

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

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

Schema description coverage is 88%, so the schema already documents the parameters, and the baseline is 3. The description loosely maps the op enum to operations ('switch off/on (disabled)') and mentions group-membership editing, adding marginal meaning but no syntax or format 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 (Edit) and resource (a host in fleet.yaml) and then disambiguates scope explicitly with 'this machine's inventory, not the server', which separates it from server-side siblings like remnanode_update or host_inspect. It also enumerates the operations covered (add, change, move, disable/enable, remove), so an agent knows the tool's full remit without opening the schema.

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

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

The description explains the dry-run-then-apply workflow (dry run default, apply writes), which implicitly tells the agent how to invoke it, but it names no alternative or 'when not to use' condition. With siblings like fleet_hosts and host_inspect present, the absence of routing guidance leaves selection 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the critical safety trait 'No host is contacted' and identifies fleet.yaml as the source, but it omits whether local files are modified, permission requirements, and return/pagination behavior. Adequate but with clear gaps.

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 resource and contents, followed by the key safety constraint and usage pointer. Every sentence earns its place with no redundant text.

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

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

There is no output schema, and the description does give a return-shape hint ('hosts with address, roles, tags, groups, services'). However, it does not mention the richer details fields such as logs, policy, and bootstrap settings, and does not describe pagination or permissions. Complete enough for a simple inventory tool, but not fully comprehensive.

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 the target filtering syntax and the details flag are fully documented in the schema. The description mentions host attributes but adds no parameter meaning or syntax beyond what the schema already provides; 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?

States a specific resource — the fleet.yaml inventory of hosts and their address, roles, tags, groups, services. It distinguishes itself from sibling host-* tools by explicitly saying 'No host is contacted' and positions itself as the starting point for names used by other 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?

Explicitly says 'Start here to learn the names used by every other tool,' which gives clear first-step guidance. It also implies when to prefer it over host-contacting siblings via 'No host is contacted,' but it does not name a specific alternative or state exclusions.

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

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

With no annotations, the description carries the full burden and it does so well: it discloses the default sort ('failures first'), the hidden-by-default stock OS jobs, and an important domain caveat that cron does not log results so only the last start is known for cron entries. This is genuinely useful behavioral context beyond the schema, though it omits auth/permission expectations.

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

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

Three dense sentences that front-load the resource scope before the caveats, with no filler. Slightly packed, but every clause (scope, fields, cron limitation, default filtering) 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 zero-required, fully documented 3-param read tool with no output schema, the description supplies what an agent needs: what is returned, the default filtering, and the sorting. The absence of any annotation layer is partly compensated, though auth/permission context is unaddressed.

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 per-parameter descriptions already documenting all, target, and failedOnly, so the baseline is 3. The description reinforces the all=true behavior and the failed-only framing but adds no syntax or format detail beyond what the schema already states.

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 concrete resource (scheduled jobs) and scopes it precisely: systemd timers and cron jobs across every host. It even enumerates the fields surfaced (schedule, last run, next run) so an agent knows this is a read/list surface distinct from job_status or schedule_toggle.

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 rather than stated: the description clarifies default filtering ('stock OS jobs hidden unless all=true or they fail') but never says when to reach for this tool versus siblings like job_status, cron_logging, or schedule_toggle. No explicit alternatives or 'when-not' guidance is offered.

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?

Without annotations the description carries the full burden, and it does disclose real behavior: output is persisted to the local state dir, changes are diffed against the previous snapshot, and it can be driven from cron. It still omits whether the tool touches the hosts (read-only vs mutating), any permission/auth requirements, runtime cost, and where the state dir lives.

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

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

Front-loaded with the core action, followed by scope and then the scheduling tip; every sentence serves a purpose. The long parenthetical enumeration of captured subsystems is dense but earns its place as scope definition.

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

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

For a two-parameter tool with no output schema or annotations, the description covers purpose, captured scope, the reporting behavior, and scheduling. Remaining gaps are operational: state dir location, host-side impact, and how to retrieve past snapshots or diffs named by the sibling tools.

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 'reason' and 'target' are already documented in the schema; the baseline is 3. The description only indirectly enriches them, by implying the 'daily' reason value through the cron example, and adds no selector syntax or scoping 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 plus resource: record host configuration state and report the diff since the previous snapshot, with the captured surface enumerated (packages, units, containers, ufw, ports, sshd, keys, cron, sysctl, certs, tracked files). That is far more concrete than a title restatement. It stops short of naming related siblings such as fleet_changes or snapshots_list, so an agent cannot tell from the text alone which one surfaces the history it just wrote.

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 operational context: run it on a schedule (e.g. daily cron `mia call fleet_snapshot`) to build a change history. That tells the agent when this tool is the right one, namely a recurring baseline capture. No when-not guidance or explicit alternative is offered for ad-hoc inspection of existing snapshots or diffs.

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

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

No annotations are provided, so the description carries the full burden, and it does substantial work: probing happens over ssh in parallel, per-host metric set is enumerated, open issue codes are summarized rather than detailed, and with target=all non-fleet tailnet devices are added with Linux machines probed under the default ssh user and others reported by online state. It omits timing/timeout/rate-limit and credential behavior, which is the 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?

Front-loaded with the core purpose and dense with useful detail; nearly every clause carries information. It is a long em-dash-chained sentence, so readability suffers slightly, but there is little 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?

With no output schema and no annotations, the description must cover both behavior and return content, and it enumerates the returned metrics and issue codes well enough to set expectations. It still does not describe the response structure (per-host objects, error/offline representation) or failure handling, leaving a modest gap for a probe tool that depends on SSH reachability.

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, but the description goes beyond the schema by explaining the semantic interaction between the two parameters: 'target all' triggers tailnet device enumeration and the 'tailnet' flag governs it, plus how those extra devices are handled. That is real added meaning, not a restatement.

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 ('one-screen health of the fleet') and enumerates exactly what is collected per host (uptime, load, memory, disk, updates/reboot, container, certs, Tailscale, panel, users online). It also explicitly routes the agent to the sibling that owns the detailed view ('details: fleet_audit'), so it is distinguishable from fleet_hosts/fleet_audit without opening a 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 clear context for when this is the right tool (a single-screen fleet health summary) and names the alternative for the deeper case ('details: fleet_audit'). It does not state explicit exclusions or prerequisites (e.g. whether SSH reachability or credentials are required), so it stops short of full when/when-not 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?

No annotations are provided, so the description carries the full burden. It says the call checks for success, which hints at a return signal, but it omits that the default is a dry run requiring a planHash to apply, that it rolls out across multiple hosts (default role:remnanode), and that it is a disruptive mutation.

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 sentence with no filler, and the action is front-loaded. The parenthetical service and script names add identification value without bloating it.

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 six-parameter fleet mutation with no annotations and no output schema, the description is thin: it never mentions the dry-run/apply gate, the fleet-wide default target, the batch/rolling behavior, or how success is reported, leaving the agent to reconstruct all of that from the schema.

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

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

Schema coverage is 100%, so all six parameters including target, apply, and planHash are already thoroughly documented in the schema. The description adds nothing about parameter usage, 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?

States a specific verb (run) and resource (the roscomvpn geoip/geosite updater), naming the underlying service and script, which distinguishes it from sibling update tools like blacklist_update or cert_renew. It does not explicitly contrast itself with any sibling, but the resource is unambiguous.

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

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

The word 'now' implies an immediate synchronous run rather than a scheduled one, but there is no explicit when-to-use guidance, no mention of the dry-run-then-apply workflow the schema implies, and no routing to alternatives such as fleet_schedule or scenario_start.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses that a fresh registration token is fetched from the Gitea API at run time and passed via environment variable, never through the plan or journal (a meaningful security/secrets disclosure), and that post-conditions are verified (act_runner active, label exactly node-<name>:host). It stops short of stating required Gitea API credentials/permissions or reversibility.

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 every clause (token handling, verification, label correctness) adds operational value. It is dense with parentheticals and reads as one long sentence, which slightly hurts scannability, but there is no filler.

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

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

For a 6-parameter mutation tool with no annotations and no output schema, the description covers the mechanism, the secrets handling, and the success verification. It does not describe the dry-run/planHash return content, though the schema partially covers the apply workflow, leaving a small gap.

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?

With schema coverage at 67%, the description adds real meaning beyond the schema: it documents the default script path and its positional arguments (<name> <token>), and explains the name-to-label mapping (label rendered as node-<name>:host). It leaves repo/apply semantics largely to the schema, so it complements rather than duplicates.

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 (register) and resource (Gitea Actions runner on a node), plus the exact mechanism used (runner bootstrap script from the MIA_REPOS checkout, default ops:deploy/bootstrap-node-runner.sh). It clearly distinguishes itself from sibling gitea_runner_remove (the inverse operation) and gitea_runners (read-only listing).

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 conveys the operational context (registering a runner via a repo script, dry-run/apply implied by the schema) but never explicitly states when to choose this over alternatives or when not to use it. It assumes the agent already knows it wants to register a runner; sibling gitea_runner_remove is not referenced for contrast.

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

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

With no annotations, the description carries the behavioral burden and does disclose two safety-relevant traits: a dry run previews the target and a busy runner causes refusal. It stops short of stating irreversibility, required permissions, or the failure response, which matters for a delete tool.

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

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

A single tight sentence with the destructive action front-loaded, followed by the preview behavior and the refusal condition. 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?

With no annotations and no output schema, the description adequately covers purpose, preview semantics, and the key failure mode; the schema handles input parameters. It could still note reversibility or permissions, but an agent has enough to call 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 description coverage is 100%, and the schema already fully explains name, apply, and planHash including the planHash single-use constraint. The description's mention of 'dry run' adds only mild reinforcement, so 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 and resource — 'Delete a runner registration in Gitea' — and the parenthetical 'a node taken out of service' clarifies what deletion means. This distinguishes it from sibling gitea_runner_register and gitea_runners without needing their 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 real usage context: the dry-run-then-apply workflow is implied, and the precondition 'a busy runner is refused' tells the agent when the call will fail. It does not explicitly route to a sibling or state when not to use it, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses required config (GITEA_URL + GITEA_TOKEN) and the shape of each runner record, but never states that the operation is read-only/no-side-effect, nor mentions pagination or result volume. Auth context is a plus; the safety profile is left to inference.

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 dense but well-structured sentence: resource first, returned fields in the middle, purpose at the end. No filler. Slightly overloaded with the parenthetical credential note, 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?

By enumerating the returned fields, it usefully substitutes for the absent output schema. But the single filter parameter is left entirely unexplained and the read-only nature is not asserted, so the definition is not fully complete for an agent to call it precisely.

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 defines a 'filter' parameter with 0% description coverage, and the description never explains it — whether it filters by name, online status, label, or something else. With a parameter present and undocumented in both places, the description fails to compensate for the schema gap.

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 resource (Gitea Actions runners) and enumerates the returned fields (name, online/offline, busy, labels), which makes the read-only inspection intent clear. It does not explicitly name the sibling it contrasts with (gitea_runner_register / gitea_runner_remove), so it falls short of the top band.

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?

"to spot stale registrations and runners that announce another node's label" gives the agent a motivating use case. However, it never states when to prefer this over gitea_runner_remove or gitea_runner_register, nor any prerequisites, leaving the when-to-use decision implicit.

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

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

With no annotations, the description carries the full burden. 'Watch traffic' implies a passive read-only observation and it discloses the output shape (total plus per-address-family), but it says nothing about permissions, whether it queries remote hosts, sampling windows, or rate limits.

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 that leads with the metric and scope before the use cases. Dense but each clause contributes; slightly long but no filler.

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

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

For a two-parameter, zero-required read tool with no output schema and no annotations, the description supplies the missing return-value context (total and by remote address family) and the operational intent. Only target-selector behavior and access requirements remain unexplained.

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 50%: the 'target' parameter is fully documented in the schema, while 'port' has only constraints. The description merely restates the 443 default and adds no meaning beyond it, and does not clarify the target selector syntax or what 'all' resolves to.

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 resource and scope: established TCP connections per host on a local port, broken down by total and remote address family. It is clearly distinguishable from a generic port listing, though it never names or contrasts with the sibling host_ports, which an agent could easily 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?

Gives concrete operational scenarios for use — watching traffic migrate from an old ingress to a new one, or draining before node removal — which tells the agent when this tool is the right call. It stops short of explicit exclusions or naming an alternative 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?

No annotations are supplied, so the description carries the full burden and does well: it states contents are never displayed, that a plan reports sha256/size on source and each target, that existing targets are archived to /root/mia-backup-<time>.tgz beforehand, and that dry-run/apply gates on a planHash. It omits auth/permission requirements and how the relay connection is established, leaving a small gap for a mutation tool.

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

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

Front-loads the verb and resource, then layers safety behavior and the `set` special case. The long parenthetical enumerating example paths is dense but informative; the run-on first sentence is slightly heavy, but every clause carries operational meaning.

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

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

For a 10-parameter, no-output-schema mutation tool, it covers the destructive/backup behavior, dry-run workflow, hashing, and the file-transformation caveat. Return-format detail is largely unnecessary since no output schema exists, though the plan/apply lifecycle could be spelled out a bit more.

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 90%, so the baseline is 3. The description only adds meaning for `set` (KEY=value lines changed on the way, with a LOG_NODE_NAME example) and touches planHash validity; the other parameters are already fully explained by the schema, so little net value is added.

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 (copy) and resource (files/directories) with explicit scope: from one host to others, relayed through this machine. Distinguishes it from the many read/edit siblings (host_file_read, host_file_edit) by describing a multi-host push operation and by enumerating the exact config paths it is meant for.

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

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

Gives clear situational context (the manual work done 'when moving an ingress or cloning a node'), which tells the agent when this tool applies. It does not name alternatives or explicit exclusions (e.g., single-host editing vs host_file_edit), so it falls short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and falls short. It never states that the call is read-only or side-effect free, and the word 'restarts' is genuinely ambiguous — it could mean reporting restart counts or triggering restarts, a distinction that materially changes safe usage.

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 compact sentence with no filler, and the covered subdomains are front-loaded. It loses a point only because the fragment omits any verb, which reduces rather than improves clarity.

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 and no annotations, so the description should explain what a call returns; it partially does by listing state, image, restarts, and disk usage, but omits return shape, aggregation across containers/projects, and whether anything is mutated. Adequate but incomplete for a tool with zero structured behavioral support.

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% for the single 'host' parameter, including the pointer to fleet_hosts, so the schema does the work. The description adds nothing about the host parameter or how it is resolved, which fits the baseline 3 for a fully documented, one-parameter tool.

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 a resource (Docker on a host) and enumerates the subdomains it covers (containers, compose projects, disk usage), but it is a bare noun phrase with no verb, so an agent cannot tell whether it reads/inspects Docker state or acts on it. It is distinguishable from siblings like host_services_discover or host_inspect only by the Docker keyword.

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 when-to-use guidance, no prerequisites, and no mention of alternative tools such as host_inspect, host_services_discover, or disk_cleanup that overlap in scope. The agent must infer that this is the Docker-specific inspection path.

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

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

With zero annotations the description carries the full burden, and it does add real traits: sudo escalation, parallel execution (batch 10), per-host output tails, and journaling of the command. It stops short of the safety profile an arbitrary-execution tool needs - blast radius, default root execution, irreversibility - so the disclosure is partial rather than complete.

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 short sentences with the core capability front-loaded and no filler; every clause carries information. Slightly under-elaborated rather than bloated, so it is efficient but not maximally informative.

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

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

For a 9-parameter, annotation-free, arbitrary-command tool with no output schema, the description covers execution mode, output shape, and audit trail, but leaves safety framing and the dry-run/apply lifecycle entirely to the schema. Adequate, with a meaningful gap for such a high-risk 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 78%, so the schema already documents most parameters thoroughly (planHash, timeoutSec, target grammar). The description adds only marginal semantics - 'Parallel by default (batch 10)' and 'through sudo when configured' - which lightly reinforce batch and asUser but do not extend the schema's own 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 ('Run an arbitrary shell command on hosts') and immediately positions it relative to siblings with 'For anything the dedicated tools do not cover', so an agent can tell it apart from host_inspect, host_logs, host_file_edit, etc. without opening a 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?

Explicitly gives the usage condition: a fallback for gaps the dedicated tools leave. However it names no concrete alternatives and no when-not conditions (e.g. don't use for file edits, service restarts), leaving the agent to infer the 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?

With no annotations, the description carries the full behavioral burden and does it well: it discloses the dry-run default, the diff preview, the backup file naming (.bak-mia-<time>), in-place writing with owner and mode preserved, and the optional unit reload. It stops short of stating permission requirements or failure modes, but this is rich disclosure for a mutation tool.

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

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

The purpose and the two primary operations are front-loaded in the first sentence, with behavioral details following. It is dense but every sentence carries information; the only minor cost is the parenthetical example lists, which lengthen the opening without much added routing value.

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

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

No output schema exists, but the description covers the key lifecycle facts an agent needs: dry run returns a diff and planHash, apply requires that planHash, the file is backed up and written in place with permissions preserved, and a unit can be reloaded. Missing permission/auth requirements and the exact refusal condition (targets changed) is covered only via the schema, leaving a small gap for a destructive 9-parameter 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 67%, so several parameters (apply, match, reload, replace, planHash) are already documented in the schema. The description adds contextual meaning for op (clone/replace/remove) and format (plain lines, JSON, YAML with comments kept), but leaves host and path unexplained, so it only partially compensates for the coverage gap.

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 (edit) and resource (fleet registry files on a host) and grounds it with concrete examples: cloning a template node's entry for a new node, or removing a removed node's entries (node_servers.keep.txt). This is enough to separate it from host_file_read (read) and fleet_host_edit (host config), though neither sibling is named explicitly.

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 two headline scenarios (clone for a new node, remove for a removed node) implicitly tell the agent when to reach for it, and the op enum is echoed contextually. However, there is no explicit when-not-to-use guidance and no pointer to alternatives such as host_file_read for inspection, so 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?

With no annotations, the description carries the full burden and does disclose two meaningful, non-obvious traits: root elevation under sudo and automatic masking of secrets (keys, tokens, passwords). It stops short of describing truncation via maxBytes or binary-file/error behavior, but the safety-relevant disclosures are strong.

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 tight sentences, front-loaded with the core action and the mode variation, then the safety note. Every clause carries information and there is no filler.

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

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

For a tool with no annotations and no output schema, the description should ideally explain return shape and the effect of maxBytes (truncation), which it omits. The purpose, elevation, and masking details are present, so it is adequate but has clear gaps for a read tool whose output format is undefined.

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 67%: host and path are documented in-schema, while maxBytes has no description anywhere. The description does add meaning by clarifying that path may point to either a file or a directory, but it does not explain maxBytes truncation semantics, leaving the coverage gap unaddressed.

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 ('Read a file on a host') and adds a second mode ('or list a directory'), so an agent knows both file and directory paths are valid. It implicitly contrasts with the write-oriented sibling host_file_edit, but never names an alternative explicitly.

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 conditional execution context ('as root when sudo is configured'), which is useful for predicting behavior. However, it offers no guidance on when to choose this over host_exec, host_copy, or host_file_edit, so the usage boundary is left implied.

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

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

With no annotations, the description carries the full disclosure burden. It does reveal the concrete data sources and commands behind the result (ufw status numbered, fail2ban, ipset, iptables), which is genuine behavioral context beyond the schema. However, it never states that this is read-only, that it likely requires elevated privileges to query iptables/fail2ban, or how large/slow the collection is.

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 that leads with the resource ('Firewall detail of a host') before the itemized contents. The command names (ufw status numbered, ufw-blacklist.sh, MGMT-PORTS) are dense but each earns its place by specifying exactly what is returned.

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

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

For a simple one-parameter read tool with no output schema and no annotations, the description compensates well by enumerating the returned data categories, so an agent knows roughly what comes back. The remaining gap is safety/permission context, which is minor for a diagnostic read but not fully covered.

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

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

Only one parameter exists and its schema coverage is 100%, with the schema itself explaining 'host name from the inventory (fleet_hosts)'. Per calibration, high schema coverage sets the baseline at 3 even when the description adds no additional parameter meaning, and this description adds none.

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 ('Firewall detail of a host') and enumerates exactly what is collected: ufw status numbered, fail2ban jails with banned IPs, ipset blacklists, and the MGMT-PORTS iptables chain. An agent can tell this is a firewall-state inspection tool apart from host_inspect or host_ports. It lacks an explicit action verb (get/retrieve), but the resource and scope are unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as ufw_rule, fail2ban_unban, or blacklist_update, all of which live in the same sibling namespace and could be confused with a read of firewall state. The diagnostic intent must be inferred from the content listing alone.

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

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

With no annotations, the description carries the full load and 'inspect' plus the itemized contents make the read-only, broad-scan nature clear. However it says nothing about permission requirements, the potentially large response payload, latency of an all-in-one collection, or how the 'sections' filter affects returned data.

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 sentence with the scope front-loaded ('Everything about one host in one call') and no filler. The long enumeration is justified because it is literally the payload contract, though the dash-appended 'audit findings and matching panel node' items are easy to miss.

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

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

With no output schema and no annotations, the description sensibly enumerates returned contents, which is the most important information an agent needs for an aggregate read tool. It is close to complete, missing only operational notes such as read-only status, expected response volume, and how omitted sections behave.

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 are already documented, establishing a baseline of 3. The description does expand a couple of cryptic section names (e.g., remnanode includes compose, certificate, geo files) and notes audit findings and panel node are included even though they are not valid 'sections' values, which is mildly useful but not a substitute for parameter syntax detail.

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

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

States the resource precisely (one host) and enumerates the exact material returned — system, updates, units, sockets, firewall, Tailscale, docker, remnanode, services, tuning — so an agent knows this is a single-host aggregate read. It does not explicitly name the granular siblings (host_ports, host_docker, host_firewall), though 'in one call' implicitly contrasts with them.

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, no conditions, and no mention of the per-topic alternatives that overlap heavily with this tool. The phrase 'in one call' hints at the trade-off versus host_ports/host_docker/host_firewall, but the agent has to infer it.

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

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

No annotations are provided, so the description carries the full behavioral burden. "Tail logs" implies a read-only operation, but nothing states permissions, whether it touches remote hosts live, or rate/pagination behavior — though the source-resolution semantics (unprefixed names, unit:/container:/file:/journal prefixes) do add genuine behavioral context.

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

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

Front-loaded with the core action in five words, then a dense but purposeful second sentence. The example-heavy source sentence is long yet every clause carries distinct routing information, so little is wasted.

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

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

With no output schema and no annotations, the description should ideally describe return format and any host-access constraints, but it stops at invocation semantics. It fully covers the hardest part (source resolution) yet leaves the response shape and remote-execution behavior unexplained.

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 80%, so the baseline is 3, but the description goes further by mapping the ambiguous `source` string to concrete resolution rules (service name -> container stdout/systemd journal, file name -> /var/log paths, explicit prefix forms). That is meaningfully beyond the schema's terse "service name, log name, unit:<u>..." line.

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 ("Tail logs on a host") that is immediately understandable. However, it never distinguishes itself from the sibling journal_list, which presumably also surfaces journal output, so an agent must guess which to pick.

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 extensive source-format enumeration implies how to invoke the tool, but there is no explicit when-to-use guidance or routing against alternatives like journal_list or host_inspect. 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?

With no annotations, the description must carry the behavioral burden. It usefully discloses that checks run FROM the hosts and in parallel, and that tls uses TLS1.3 + h2, which is real added context. However it omits permission requirements, timeouts, and whether checks are safe/read-only, leaving meaningful gaps for a no-annotation tool.

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

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

Two tightly packed sentences: capability first, then use cases. Front-loaded and waste-free, though the parenthetical 'what a REALITY dest needs' is jargon that may not parse for a general agent.

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 diagnostic tool with no output schema, the description covers what is run but says nothing about the return format, timeouts, or how results are surfaced, which an agent may need to interpret output. Usage is well covered, but the mechanics of the result are left implicit.

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 75% and the schema already documents `to`, `sni`, and `target` in detail, with `check` constrained by an enum. The description adds meaning by implying what the `check` values do (tcp/tls/http/dns/ping/trace), but does not elaborate on `to`, `sni`, or `target` semantics beyond the schema. 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?

The description states a specific verb+resource: network checks run FROM hosts, and enumerates the check types (tcp, tls, http, dns, ping, trace). An agent can tell it is a remote diagnostic tool rather than a firewall/port/config tool. It does not explicitly name a sibling it differs from (e.g. host_ports, host_inspect), so it lands just short of 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?

Three concrete use cases are given: pick/verify a REALITY dest, check a node reaches the panel, and detect if a destination is filtered from a location. That is clear context, though it does not name explicit alternatives or exclusions to route against sibling tools.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the classification scheme (including the 'PUBLIC because ufw is off' edge case) and that process names are included, which is genuinely informative, but it never states that this is a read-only snapshot tool or whether any auth/permission is required. The disclosure is mostly about return content rather than operational behavior.

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

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

Two sentences with essentially no filler, and the core scope ('what is reachable on a host and from where') is front-loaded. The trailing 'Plus the public UFW allows.' is a slightly awkward fragment, but nothing is wasteful.

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 low-complexity, one-parameter read tool with no output schema, the description carries the return-value burden well by enumerating the classification buckets and the process-name field. The remaining gap is the absence of any sibling differentiation, but on the whole an agent has enough to call it correctly.

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

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

The single parameter 'host' is fully documented in the schema ('host name from the inventory (fleet_hosts)') at 100% coverage. The description adds nothing beyond that -- it never clarifies valid host identifiers or how the value relates to fleet_hosts. Baseline 3 applies when the schema already does the work.

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 resource -- every listening socket on a host with its exposure classification (local / tailnet-only / public-allowed / blocked by ufw / PUBLIC) plus the process name. An agent can tell what this reports without opening the schema. It does not, however, distinguish itself from adjacent siblings like host_firewall, host_connections, or host_net_check, which also deal with host reachability.

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 statement, no prerequisites, and no named alternative. The closest thing to guidance is the implication that this is an exposure/audit query, which the agent must infer rather than being told. Rival tools such as host_firewall and host_net_check are never mentioned, so the agent has no routing signal.

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

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

With no annotations, the description must carry the behavioral burden, and it discloses a lot: rolling batch-1 sequential reboots, waiting for ssh + remnanode to return before the next host, and that the dry run reports users online per node and pending-reboot state. It omits permission requirements and failure/recovery details beyond what parameters imply, so it is strong but not exhaustive.

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

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

Two dense sentences that are front-loaded with the core action and mechanism, with secondary dry-run detail trailing. Almost every clause carries information, though the phrasing is compressed enough to border on terse.

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, 8-parameter tool with no annotations and no output schema, the description supplies the operation mechanics and dry-run behavior needed to call it safely. It lacks explicit safety/permission framing and does not describe the return payload, but the pre-flight dry-run and planHash params largely cover the safety story.

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 88%, so the schema already documents nearly all parameters. The description only reinforces the dry-run visibility ('users online per node') and rolling batch behavior, adding little syntax or format detail beyond the schema's own descriptions of wait, apply, target, etc.

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 (Reboot) and resource (hosts) and immediately adds the mechanism (shutdown -r +delay) and rolling semantics. No sibling tool in the list performs a reboot, so the purpose is unambiguous and clearly differentiated.

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 a dry-run-then-apply workflow and mentions rolling batch behavior, which hints at how to use it. However it never states when to prefer this over alternatives (e.g., host_exec or service_action), nor prerequisites such as required access. Usage is implied 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?

No annotations are provided, so the description carries the full burden, and it does disclose 'Read-only' plus the exact return format (ready services:/apps: YAML for fleet.yaml) — valuable given there is no output schema. It does not discuss permissions, rate limits, or how a partial/failed discovery behaves, leaving 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?

A single dense sentence that front-loads the discovery scope, then the return format, then the read-only/one-time usage note. The parenthetical asides are informative rather than wasteful, though the breadth of listed service types makes it slightly heavy.

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, one-parameter tool with no output schema and no annotations, the description compensates well by explaining both what is discovered and the shape of the returned YAML. Only minor gaps remain around error behavior and relationship to the other host_* discovery siblings.

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

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

There is a single required parameter and schema description coverage is 100%, with the schema stating it is a host name from the inventory (fleet_hosts). The description adds no further parameter syntax or constraints, so the baseline of 3 is appropriate since the schema already does the work.

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 (discover) and resource (services running on a host), and scopes it precisely: docker compose projects, standalone containers, non-stock systemd services, and API-bearing apps. It distinguishes itself from the inventory (fleet_hosts) and from siblings like host_docker by enumerating exactly what it surfaces and what it returns (services:/apps: YAML for fleet.yaml).

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 usage context: it finds what the inventory does not yet know, and 'use it to describe a home server once' frames it as a one-time discovery step. It stops short of naming alternatives or explicit when-not conditions (e.g. vs host_inspect or fleet_discover), so it lacks the exclusions that would earn a 5.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the path is translated through Jellyfin container mounts and must exist on both host and container sides. It says nothing, however, about the dry-run/apply workflow that governs whether anything actually changes, nor about required permissions, which is a notable gap for a mutation tool.

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

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

Two tight sentences, front-loaded with purpose followed by path semantics and the scan note; no filler. It could have spent a few words flagging the dry-run default, but as written it is efficient and well-ordered.

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 6-parameter mutation tool with no annotations and no output schema, the description covers purpose, path handling, and post-scan behavior, but omits the safety-relevant apply/planHash contract even though it is central to how the call behaves. Adequate but with a clear gap given the absence of 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 high (83%), so 3 is the baseline, and the description adds real meaning beyond the schema: the path can be given as a host path (translated through container mounts) or a container path, and must exist on both sides. The schema only says 'folder, absolute (host or container path)', so the dual-existence and translation semantics are a genuine addition.

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 ('Add a folder to an existing Jellyfin library'), and the word 'existing' implicitly separates it from jellyfin_library_create, which makes a new library rather than adding a path. It is clear and specific, though it never names a sibling outright, 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?

Usage is largely implied by the purpose sentence, and 'Optionally scans the library afterwards' mildly routes around jellyfin_scan. However there is no explicit when-to-use/when-not guidance against jellyfin_library_create, jellyfin_task_run, or tdarr_library_add, so alternatives are left to inference.

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

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

With no annotations, the description carries the full burden and discloses only that library options may be copied or defaulted. It says nothing about the mutation's side effects, the fact that apply defaults to a dry run requiring a one-shot planHash, permissions, or irreversibility — all of which matter for a create operation.

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

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

Two tightly written sentences with the core action front-loaded and the options nuance trailing; no filler. Slight verbosity with the parenthetical '…' ellipsis list, but otherwise efficient.

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 an 8-parameter mutation tool with no annotations, no output schema, and 63% schema coverage, the description omits the most consequential facts: the dry-run-first/apply contract, that optionsFrom is the sole options source, and scan defaults. An agent could invoke it without realizing the default call is a no-op dry run.

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 63%, so the schema already documents several parameters (host, apply, paths, planHash). The description's only parameter-level contribution is restating optionsFrom ('copy from an existing library of your choice') plus 'with folders' for paths, adding little beyond the schema text.

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

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

States a specific verb and resource ('Create a Jellyfin library with folders'), which is enough to distinguish it from jellyfin_library_add_path (adds a path to an existing library) and jellyfin_scan. It does not explicitly name those siblings, but the verb+resource is unambiguous.

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

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

There is no statement of when to use this versus jellyfin_library_add_path, nor any mention of the dry-run/apply workflow that governs safe invocation. The only conditional offered is the internal optionsFrom behavior, not guidance about tool selection.

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

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

With no annotations, the description must carry the full behavioral burden. It adds the useful nuance that single-library scans only pull metadata/images for new items, but says nothing about whether this mutates state, what permissions/host model it needs, or how dry-run/apply interact — those mechanics live only in 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?

A single front-loaded sentence with no filler. The parenthetical clarifying single-library behavior is slightly dense but 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 tool with a dry-run/planHash workflow, the schema covers the mechanics, but with zero annotations and no output schema the description leaves the safety profile and mutate-vs-read nature unstated. It is adequate but not complete for a mutation-triggering 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 host, apply, library, and planHash are already documented. The description reinforces the library default (all libraries) and adds the metadata/images nuance, but adds no format or constraint details 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 (Scan) and resource (Jellyfin files) plus the scope distinction of one library vs all libraries, and clarifies that single-library mode only handles metadata/images for new items. It does not explicitly contrast with siblings like jellyfin_task_run or tdarr_scan, but the purpose is unambiguous.

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

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

The description implies when scanning is relevant ('new/changed files') but gives no explicit when-to-use, prerequisites, or routing to alternatives such as jellyfin_task_run or tdarr_scan. The library scope choice is described but framed as a parameter effect rather than usage 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?

No annotations are provided, so the description carries the full burden, and it does disclose a rich picture of what the call surfaces (scan state, live streams with direct-play vs transcode, failed/running tasks). It stops short of stating the safety profile, permission needs, or cost/latency traits, but for a passive status read the disclosed output behavior is substantial.

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 dense, tightly front-loaded sentence that opens with the resource and then lists the reported categories; every clause maps to a distinct piece of output. The nested em-dash parenthetical is slightly awkward but not wasteful.

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 effectively serves as the return-value contract and covers version, libraries, streams, counts, and tasks. For a read-only diagnostic of moderate complexity this is nearly complete, missing only explicitly stated limits or guarantees.

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

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

Schema coverage is 100% and the single 'host' parameter is already documented in the schema (host from inventory with apps.jellyfin/apps.tdarr). The description adds no syntax or format detail beyond that, 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?

States a specific resource ('Jellyfin on a host') and enumerates exactly what is reported: version, libraries, active streams, item counts, tasks. This clearly separates it from action siblings like jellyfin_scan and jellyfin_task_run, though it never names alternatives explicitly.

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 name and the read-only 'status' framing (check the state of Jellyfin on a host), but there is no explicit when-to-use, prerequisite, or when-to-prefer-a-sibling guidance despite many closely related tools in the 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?

With no annotations, the description carries the full behavioral burden and says nothing about side effects. It never mentions that this is a mutating action, that the default is a dry run requiring a planHash to actually execute, whether the call waits for task completion, or what happens if the task name/key is invalid.

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 no filler; the examples are compact and useful. It is arguably under-sized rather than bloated, but as written every element 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 annotations and no output schema, the description omits the two-phase dry-run/apply requirement, expected result, and error behavior. The agent must reconstruct the safety protocol from the schema, which is insufficient for correct invocation.

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

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

Schema coverage is 75%: host, apply, and planHash are documented in the schema, but the required 'task' parameter has no schema description. The description compensates by supplying example task names/keys for 'task', adding real value, though it does not clarify valid key formats or name matching rules.

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+resource ('Start a Jellyfin scheduled task') and clarifies that lookup can be by name or key, with concrete task examples ("Scan Media Library", "Clean Cache", RefreshLibrary). It does not distinguish this from the sibling jellyfin_scan, however, which may cover overlapping ground (both trigger media scans).

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 statement of when to use this tool versus jellyfin_scan or the other jellyfin_* siblings, nor any prerequisites. The only procedural guidance (dry-run first, then apply) lives in the schema parameter descriptions, not the tool description.

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

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

With no annotations, the description carries the full burden and does a good job: it discloses the returned payload (running/finished with exit code, log tail, Tailscale login URL when authorization is pending) and the connection strategy (Tailscale inventory address first, then public bootstrap address). It does not mention permission or auth requirements, so it is strong but not exhaustive.

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

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

Three sentences, zero filler, with the core purpose front-loaded and the fallback and no-argument behaviors appended in order of relevance. Every clause adds usable information.

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

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

For a two-parameter status tool with no annotations, no output schema, and 0% schema coverage, the description covers purpose, return contents, fallback addressing, and the no-jobId mode. The only meaningful hole is the semantics of the 'lines' parameter, which the agent must guess from 'the log tail'.

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 0%, so the description must compensate. It fully explains jobId, including the distinct no-jobId listing behavior, but never mentions the 'lines' parameter that controls how much log tail is returned, leaving one of two parameters undocumented.

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 resource and verb-equivalent ('State of a detached remote job') and scopes it to a concrete job type, node_bootstrap, which helps the agent separate it from the start-a-job sibling. It does not explicitly contrast itself with other status tools such as fleet_status, 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?

The conditional 'Without jobId: lists known jobs' gives an implied mode-selection rule, which is genuinely useful. However there is no explicit when-to-use guidance relative to node_bootstrap (which presumably launches the job this tool monitors) or any other status sibling, so usage is inferred 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the returned fields and newest-first ordering, but does not explicitly state that the operation is read-only, whether it requires authorization, how pagination or limits behave, or what planHash represents.

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 definition is a single front-loaded sentence with no wasted words. It efficiently communicates the core purpose, return content, and ordering.

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

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

The description partially covers the tool's behavior by naming returned fields and sorting, but it omits filter semantics, pagination/limit behavior, and usage context. With no output schema or annotations, these gaps leave the definition only adequate, not 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 description coverage is only 25%, and the description does not compensate by explaining the host, limit, or contains parameters. Only since has schema-level documentation as an ISO date/time, while the description focuses on returned fields rather than input filters.

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

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

The description clearly states the resource and content: every action the server performed on hosts, with time, host, outcome, planHash, and newest-first ordering. It is specific enough to understand the tool, but it does not distinguish this from sibling audit/history tools such as fleet_audit, fleet_changes, or host_logs.

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

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

There is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description only describes output content and ordering, leaving the agent to infer its role among many sibling tools.

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

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

With no annotations, the description carries the full burden and does well: it discloses that execution is detached over the public IP, that the firewall reset severs public SSH, that polling must go through job_status, and that the server reboots 3 minutes after success. It also reveals the two-phase baseline (bootstrap then fleet-node-seal.sh) with ipset blocklists, MGMT-PORTS and agents.

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

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

Front-loaded with the core action followed by the sequence and caveats, and every clause carries real information. It is dense and somewhat run-on, with the baseline description packed into a single sprawling sentence, but nothing is wasted given the tool's complexity.

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 complex, annotation-free, output-schema-free provisioning tool this is remarkably complete: prerequisites, side effects (SSH severance, reboot), async lifecycle, dry-run semantics, and the follow-on sealing phase are all covered. An agent has enough to reason about blast radius before invoking.

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 75%, so the schema documents most parameters. The description adds operational meaning by tying secretKey to the panel's SECRET_KEY, framing planHash as a one-shot dry-run token, and noting the Tailscale auth path (--ssh, exit node), though thinner params like hostname and remnanode remain unexplained.

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 ('Turn a fresh Ubuntu server into a node'), names the concrete script it drives, and enumerates the resulting stack. It clearly differentiates itself from siblings by positioning scenario_start as the full-sequence runner and fleet_audit as the gap reporter.

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 the agent: scenario_start runs the whole sequence while this is 'only the start of the current baseline', fleet_audit shows what is missing, and job_status is the polling mechanism. It also states the prerequisite (domain A record pointing at the server) and the apply/planHash gate.

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

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

With no annotations, the description carries the burden and does well: it discloses the rolling batch-1 default, the per-node pull/up sequence, the wait for container plus panel connection, and the fail-stop behavior. It omits auth/permission needs and the time cost of a full rollout, keeping 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?

Two dense sentences, zero filler, with the core action and mechanism front-loaded and the rollout/failure semantics following. 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 annotations and no output schema, the description covers the workflow, the dry-run/apply gate, and failure handling adequately, and the schema covers the return-adjacent planHash. It stops short of noting duration, auth prerequisites, or blast radius (e.g. prune removing dangling images).

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters including defaults and planHash semantics. The description reinforces the batch-1 default and the pull/up behavior but adds little on parameter syntax beyond what the schema provides; 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 (Update) and resource (remnanode / remnawave node image on nodes), then spells out the exact mechanism: compare against Docker Hub, then per-node `docker compose pull && up -d`. An agent can identify this distinctly among the fleet siblings without opening the schema.

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

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

The description implies usage through the dry-run/apply workflow and the 'stops at the first node' rollout semantics, and the apply param clarifies the plan step. However, it never states when to prefer this over alternatives (e.g. apt_upgrade or service_action) or when not to use it, leaving routing to inference.

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

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

With no annotations, the description carries the full burden and discharges much of it: it discloses ssh delivery, root execution from a temp dir, cleanup afterward, that the checked-out version is pinned and shown with commit/uncommitted-changes/hash, that secrets are read from mia's environment and never displayed, and that installTo keeps the prior copy as .bak-<time>. It omits explicit permission/auth requirements and error-handling traits, so it is not exhaustive.

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

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

Information-dense and front-loaded: the core action appears first, followed by delivery/execution behavior, then provenance and the secrets model. It is fairly long, but nearly every clause carries new information, so it earns most of its length.

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 15-parameter, no-annotation, no-output-schema tool this is a fairly complete description: it explains the execution model, the safe plan/apply flow, provenance, and the secrets and install variants. Remaining gaps (behavior of timeoutSec, batch, continueOnError, skipUnreachable) are covered by schema descriptions, so an agent has enough to call 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 high (87%), setting a baseline of 3, but the description adds meaning beyond the schema for the workflow-critical params: envFrom (secrets sourced from mia's own environment, never shown), with (companion files kept at same relative paths), apply/planHash (dry-run then apply, refused if state changed), and installTo (cron re-runs the installed copy). It adds genuine semantics rather than restating 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+resource: it runs the user's own fleet scripts from a local repo checkout on hosts, and names the exact kinds of scripts (deploy/migrate-blacklist.sh etc.). This clearly distinguishes it from generic remote-execution siblings like host_exec, since it emphasizes 'exactly the checked-out version runs' with commit/hash provenance.

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 lays out the intended two-phase workflow (dry run with apply=false and a planHash, then apply=true) and explains the envFrom/secrets path, which is real usage guidance. It does not explicitly contrast with alternatives such as host_exec or service_action, so it stops short of a full when/when-not routing statement.

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

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

No annotations are provided, so the description carries the full burden; it discloses that the probe is read-only, that only one handshake per pair is performed (low-impact, bounded), that the source host is only read and nothing changes there, and that resolution is forced via --resolve rather than DNS. It omits timing/timeout behavior and error handling, keeping 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?

The core question is front-loaded and the total length is reasonable for the amount of mechanism conveyed. It is dense with parentheticals and environment-variable names, which makes it a heavy read, but almost every clause carries operational meaning.

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 correctly enumerates the return verdicts (ok | partial | blocked-ru | down) and explains what each means, including the DPI/TSPU inference behind blocked-ru. It leaves secondary gaps — probe duration, timeout/failure behavior when a vantage host is unreachable — that an agent planning around this call would want.

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 meaning beyond it: it ties MIA_PROBE_FROM/MIA_PROBE_IFACES/MIA_PROBE_CONTROL to the probing model, clarifies that 'ifaces' are ISPs and that 'from' is read-only, and explains that address resolution is forced rather than DNS-driven. That is genuine semantic value over the schema text.

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

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

Opens with a precise, specific question — whether an address is reachable from Russia or any censored network — and immediately names the mechanism (per-ISP TLS handshake plus datacenter control). The scope is narrow and distinctive enough that an agent would not confuse it with generic siblings like host_net_check or host_ports.

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 a clear usage context: it is the gate to run before and after any address switch (ingress, new node), and it instructs rolling DNS back first when the verdict is blocked-ru. It gives strong context but never names an alternative tool or an explicit when-not-to-use condition.

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

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

With no annotations, the description carries the full burden. It discloses the return shape (parameters, prior runs, and step log when run is supplied), which is genuinely useful, but it omits the read-only nature, any pagination/limit behavior, and error conditions for an unknown run.

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

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

Two dense sentences with no filler; the resource is front-loaded and the parameter behavior is appended. The parenthetical example list is slightly heavy but earns its place by clarifying what a 'runbook' 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?

For a one-parameter, no-output-schema list tool, the description covers what is returned and the parameter's effect, but it omits sibling differentiation and invocation context, so an agent still has to guess how it relates to scenario_start and scenario_step.

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 0% for the single 'run' parameter, so the description must compensate. It does explain the parameter's effect ('the step log of that run'), but not its expected format (ID vs name) or what happens when omitted, leaving the semantics only partially covered.

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 concrete resource — runbooks (scenarios) for whole operations — plus what is returned: their parameters and the runs started so far, with step-log detail when run is set. It is clear enough to act on, but it never names or distinguishes itself from the sibling scenario_start / scenario_step 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?

There is no explicit when-to-use or when-not-use guidance, and no alternatives are named. The only usage-adjacent statement is 'With run: the step log of that run,' which hints at the parameter's effect but does not tell the agent when to prefer this tool over scenario_step.

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

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

With no annotations, the description carries the full behavioral burden and does well: read-only steps auto-run, while the first mutating step returns a dry-run plan and waits for approval. It omits error handling, auth requirements, and idempotency details, so it is not fully complete.

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 compact sentences: purpose first, then behavioral model, then the required next action. Every sentence is informative and well ordered for an agent scanning the definition.

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

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

Given no annotations and no output schema, the description adequately explains the critical dry-run and approval workflow. The main gap is parameter documentation, though the required 'scenario' is implied and 'params' is optional.

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 0% across two parameters. The phrase 'Start a runbook' loosely implies what 'scenario' means, but there is no explanation of the optional 'params' object, its keys, or expected formats, so the description barely compensates for the empty schema.

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

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

The first sentence gives a specific verb ('Start') and resource ('runbook'), making the purpose unambiguous. It also distinguishes itself from the sibling scenario_step by presenting scenario_step as the continuation tool rather than the starter.

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

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

It clearly states when to call the sibling scenario_step (only after owner approval) and instructs the agent to show the plan to the owner. It does not explicitly state when not to use scenario_start or compare it against scenario_list, so it falls short of full alternative 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?

With no annotations the description carries the full burden, and it does well: it discloses the safety constraint that apply requires the owner's explicit yes for this specific step, that runs are persisted and resumable via retry, and that the call returns what happened plus the next pending step.

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

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

Front-loaded with the core action and packed with meaning; the parenthetical glosses on each decision earn their place. Dense and slightly run-on, but no wasted sentences.

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, but the description covers return values and persistence. However it omits how a 'run' is obtained (presumably from scenario_start) and how params (nested object) interacts at call time beyond the schema note, leaving a gap for a mutation tool with no 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 only 33%, so the description must compensate. It richly explains the decision enum (apply/done/skip/retry), which is more than the bare enum, but the required 'run' parameter is left unexplained in both schema and description — where a run id comes from is never stated.

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: answering the step a run is waiting on, and names the four decision values with their meanings. An agent can tell this is the step-resolution tool distinct from scenario_list/scenario_start, though it never explicitly names those 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?

Explains when each decision applies: apply only with the owner's explicit yes, done for a manual step the owner finished, retry to re-check/re-plan. This is clear per-decision guidance, but it gives no explicit routing rule versus scenario_start or scenario_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?

With no annotations, the description carries the full burden and does well: it discloses the concrete side effects (disable/enable --now, reset-failed of the timer's service, run = start its service), the cron mechanism (line commented with «#mia-off »), the backup copy written to /root/mia-backup, and explicit reversibility. It stops short of permissions/auth requirements and error behavior, so a 4 rather than 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 the one-line purpose before the systemd/cron detail, and every clause carries information (exact commands, backup path, reversibility). It is dense and semicolon-chained into a single long statement, which slightly hurts scanability.

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 an 8-parameter mutation tool with no annotations and no output schema, the description covers the mutation semantics, branching, and reversibility well. The two-phase dry-run/planHash safety workflow is only in the schema, and no return/error expectations are given, leaving minor gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the timer-vs-cron branching that motivates the unit/cronFile/cronLine/cronUser parameter groups and explains the «#mia-off » marker tied to cronLine, but adds no syntax or format 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: 'Switch a scheduled job off / on, or run a timer now', and splits the two concrete cases (systemd timer vs cron job) with the exact operations applied to each. An agent can tell exactly what state change this accomplishes without opening the schema.

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

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

The action semantics (disable / enable / run) structure the usage, and 'Reversible' hints the operation is safe to retry, but there is no explicit statement of when to prefer this over siblings like service_action or fleet_schedule, and no prerequisites (host access, required state) are given. Usage is implied rather than guided.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: rolling by default, batch size 1 for disruptive actions, and post-action verification that the service must be up again. It stops short of disclosing the dry-run/apply workflow and the consequence of a failed rollout, which the schema hints at.

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

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

Two dense sentences, front-loaded with the verb list and scope. The long parenthetical inventory example is informative but slightly bloats the sentence; overall it stays efficient with minimal waste.

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 an 8-parameter mutation tool with no output schema, the description covers scope, strategy, and verification adequately. It is not fully complete because the dry-run-then-apply contract and failure mode are left entirely to the schema.

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

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

Schema coverage is 88%, so the schema already documents almost every parameter including the apply/planHash fingerprint workflow. The description adds only a partial gloss (update = compose pull + up -d, service list sources from inventory), which is useful but not beyond the schema baseline.

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

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

States specific verbs (restart/start/stop/update/recreate) applied to a clear resource (a service), and enumerates what counts as a service: a compose project, systemd unit, or container from the inventory. An agent can distinguish this from siblings like host_reboot or remnanode_update without opening the schema.

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

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

The description conveys operating intent (rolling default, batch 1 for disruptive actions, verified up again) but never says when to choose this over siblings such as host_reboot, remnanode_update, or host_exec, nor any preconditions. Usage is implied through the action list 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?

With no annotations, the description carries the full burden, and it does disclose two real behavioral traits: results are ordered newest first, and the call has two distinct modes depending on whether host is supplied. It stops short of stating that this is a read-only operation, whether any pagination or limits apply, or what authentication is needed.

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?

At one sentence it is appropriately short and the ordering hint is front-loaded, so it respects conciseness. The second clause is garbled enough that brevity has come at the cost of clarity, which keeps it from earning a 4.

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, no annotations, and no parameter documentation, so the description is the only artifact an agent has. It omits the return shape (what fields a snapshot record contains) and the identifier format for the one parameter, leaving the definition under-specified for invocation.

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

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

Schema description coverage is 0% for the single optional 'host' parameter, so the description must compensate and it partially does: supplying host scopes results to that host's snapshots while omitting it changes the result set entirely. It never clarifies the accepted host identifier format, so meaning is incomplete but directionally useful.

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 conveys that this returns recorded snapshots (newest first) and implies a dual mode where omitting the host returns hosts that have snapshots. However the phrasing 'or the hosts that have any' is grammatically incomplete and never names the action as a list operation, so the purpose is inferable but not crisp. It also does not distinguish itself from the sibling fleet_snapshot.

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

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

There is no explicit guidance on when to call this versus the related fleet_snapshot or fleet_changes tools, and no stated prerequisites. The implicit with-host vs without-host behavior is the only hint at usage, and it must be reverse-engineered from a cryptic clause.

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

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

With no annotations, the description carries the burden and does well: it discloses the required TAILSCALE_API_KEY, the dry-run-first workflow, the refusal gating on online/inventory state, and the force override. It stops short of saying whether removal is reversible or what happens to DNS/inventory records afterward, so it is strong but not exhaustive.

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

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

Two sentences, front-loaded with the action and scope, with the dry-run/refusal nuance trailing. Every clause carries information, though the parenthetical credential note and the compound refusal clause make it slightly dense.

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 4-parameter tool with no annotations and no output schema, the description covers auth, the dry-run/apply handshake, and the safety gate. What is missing is post-removal state (does it leave the fleet inventory, DNS records, or is it re-joinable), which an operator would want to know.

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 apply, force, planHash server-side one-shot semantics. The description reinforces the force behavior but adds little syntax or format detail beyond what the schema states, 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?

Names a specific verb and resource ("Remove a machine from the tailnet") plus the underlying API and credential, and the phrase "last step of taking a server out of service" cleanly separates it from siblings like tailnet_join and tailnet_devices.

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 clear situational context (final decommissioning step) and preconditions: an online device or one still in the enabled inventory is refused unless force is set. It does not name an alternative tool for just inspecting the device, but the when-to-use 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?

With no annotations, the description carries the full burden, and it does add real behavioral context: the two possible data sources and the fallback logic, plus an enumeration of the fields returned (online/last seen, OS, version, update availability, key expiry, tags, host/panel mapping). It stops short of stating permissions or explicitly labeling the operation read-only.

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

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

A single dense sentence, front-loaded with the resource scope before the parenthetical about data source. It packs a lot of field information without wasted words, though the parenthetical interrupt is slightly awkward.

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 no output schema and two optional filters, the description covers the data source and the content of each returned record, which is enough for an agent to call it correctly. Missing only explicit safety/permission framing, which is minor here.

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% (both `filter` and `offlineDays` are documented in the schema), so the baseline is 3. The description adds no meaning for either parameter beyond what the schema already provides.

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

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

The description states a specific resource (every device of the tailnet) and enumerates the per-device attributes returned, so an agent can distinguish it from siblings like tailnet_join or tailnet_device_remove. It does not explicitly name those siblings, but the enumeration scope makes its role unambiguous.

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

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

Usage is only implied: the agent infers it should call this to inventory devices. The parenthetical explains the data-source fallback (TAILSCALE_API_KEY vs local `tailscale status`), which is useful context, but there is no explicit when-to-use, when-not-to, or named alternative.

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