sysknife

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so "read-only" in the description is redundant with structured data. It does add scope (all loaded profiles) and maps to aa-status, which is modest but real context beyond annotations; no permission or output-shape details.

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 line that front-loads the action name, the verb, the resource scope, and the parameter/safety summary. 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 zero-param, read-only status probe with full annotation coverage, the description is sufficient to select and invoke it. The only omission is what the returned profile statuses look like, which is minor given there is no output schema to rely on.

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

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

Zero parameters, so the baseline is 4. The description correctly confirms "no params," leaving nothing ambiguous about what inputs to supply.

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 (show status) and resource (all loaded AppArmor profiles), plus the underlying command aa-status, so an agent knows exactly what it retrieves. It is clearly separable from siblings like sysknife_ufw_status or sysknife_fail2ban_status by subject, though it never explicitly states those distinctions.

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?

"No params; read-only" implies this is a safe inspection call to make when AppArmor state is needed, but there is no explicit when-to-use, when-not-to-use, or alternative named. Usage is inferable from the subject matter rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description mostly restates 'read-only' and 'no params' (redundant), adding only the 'recent' scope hint — it does not explain how far back history goes or what entries contain.

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?

Single short line, front-loaded with the action and resource. Slight waste in repeating 'read-only' twice and 'no params', which duplicate the annotations, but overall very tight.

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 no-param read with full annotation coverage and no output schema, the description is serviceable. However, it leaves 'recent' undefined (time window, entry count) and does not hint at return content, which would help an agent decide when this is the right call.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly notes 'no params', matching the empty schema, with nothing further needed.

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

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

States a specific verb and resource ('show recent apt transaction history') and names the underlying action AptHistoryList. An agent can distinguish it from apt_list_installed/apt_show/apt_list_upgradable based on 'transaction history', though the differentiation is implicit rather than explicit.

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 'recent apt transaction history' but the description never states when to prefer this over apt_show or apt_list_installed, nor does it give exclusions. Adequate for a simple no-param read, but no explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description's two "read-only" mentions add nothing. The one piece of extra context is the dpkg -l backing command, which hints at output shape and package-manager scope.

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?

Very short and front-loaded, but it wastes words: read-only is asserted twice and the internal action name `AptListInstalled` is redundant with the tool name. Trimming to a single clause would lose nothing.

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-param read-only listing tool with full annotation coverage and no output schema, the description says enough to call it correctly. A brief note on what the result contains (package/version fields) would make it 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?

Zero-parameter tool, so the baseline is 4. The description correctly confirms "no params", matching the empty schema with additionalProperties true.

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

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

States a specific verb and resource ("list all installed packages") and names the underlying mechanism (dpkg -l), which distinguishes it from apt_list_upgradable, apt_show, or apt_search. It does not explicitly contrast those siblings, 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 dpkg -l note implicitly scopes the tool to dpkg-managed packages (as opposed to snap/flatpak listings), but the description never states when to prefer this over apt_list_upgradable, apt_history_list, or snap_list. Usage is left to be inferred from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data; the description's 'read-only' appears twice, adding no new information. The 'no params' note is useful but there is no hint about the shape of results (package names/versions/count), which is the only behavior left unexplained.

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?

Very short and front-loaded: action name, one-line behavior, scope, then usage examples. The only waste is the redundant 'Read-only ... read-only' repetition, which could have been said once.

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?

A zero-parameter, read-only list tool whose safety semantics are fully carried by annotations and which has no output schema; the description covers purpose and invocation triggers adequately. A brief note on what the listing contains would fully close the 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?

Parameter count is zero, so the baseline is 4, and the description correctly and explicitly states 'no params', confirming there is nothing to supply. Nothing further is needed for a no-argument 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?

States a specific action and resource: 'list packages with available upgrades', which is concretely distinct from listing installed packages or apt history. It does not explicitly name the sibling it is not (sysknife_apt_list_installed, sysknife_apt_history_list), so differentiation is inferable rather than stated.

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 trigger phrases — 'are there pending updates?' and 'what updates are available?' — that map cleanly to the agent's intent. It gives no explicit when-not guidance or named alternative for the installed/history variants, so the routing guidance is clear but not complete.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the description's 'read-only' (stated twice) adds nothing. It also does not clarify that 'apt repos' is a local cache lookup rather than a network fetch, which would have been genuinely useful given openWorldHint=false.

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 and short, but it wastes space on a framework prefix ('SysKnife action `AptSearch`') that restates the tool name and on repeating 'read-only' even though it is also in the annotations. Roughly a third of the sentence does no work.

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

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

For a zero-parameter, non-destructive search with no output schema, the minimum is present: action, resource, and the required term. However, an agent still cannot tell what a hit looks like (package name only, version, repo) or that the search is against local package metadata.

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

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

The input schema declares no properties at all, so the description is the only place that surfaces the 'term' argument and marks it required with an asterisk. That compensates for a real schema gap, though it gives no format or matching-behavior detail (substring vs regex).

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?

Clear verb + resource: 'search apt repos for packages', which distinguishes it from sibling read tools like apt_list_installed, apt_show, and apt_history_list. It stops short of naming those siblings explicitly, so it earns a 4 rather than 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 only implied by the phrase 'search apt repos for packages' – an agent can infer this is for locating a package by term. There is no explicit when-to-use / when-not-to-use guidance and no mention of apt_show or apt_list_installed as alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so 'read-only' stated twice in the description is pure repetition. The only added value is knowing the response content (version, deps, description); nothing about failure modes or missing-package behavior is disclosed.

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?

Short and front-loaded — the action and its output content come first. Minor waste: 'read-only' appears twice (opening clause and trailing clause) and the internal code name is redundant with the tool 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?

For a simple read-only query with full annotation coverage and no output schema, the description is almost adequate. The unresolved contradiction between 'package*' being required and a zero-parameter schema is a real gap an agent would hit on first invocation.

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

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

The schema declares an empty object with additionalProperties=true (zero named parameters), yet the description asserts 'param: package*' as required. That mismatch is actively confusing: an agent cannot tell whether to pass a package name as a named field, a positional value, or nothing at all. The description does not add usable semantics here; it introduces ambiguity.

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: 'show package details (version, deps, description)'. That clearly distinguishes it from sysknife_apt_list_installed and sysknife_apt_list_upgradable, though it never explicitly contrasts with sysknife_apt_search.

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 content listed (version, deps, description), but the description never says when to prefer this over apt_search or apt_history_list. No exclusions or alternatives are named despite many closely related siblings.

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 declares the tool read-only, lists the return fields, and discloses a subtle interpretation caveat (intact is not the same as complete attribution). It doesn't mention any access requirements (e.g., reading protected audit logs may need elevated privileges) or cost/latency, which keeps it below 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?

It is front-loaded with the core action and return values, and each sentence contributes something (mechanism, outputs, interpretation guidance, safety note). The middle sentence about rows_censused and attributed_rows is dense but justified because it prevents misreading the status.

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?

Although an output schema exists, the description summarizes the return values and adds the crucial interpretation warning that structured fields alone would not convey. Combined with the read-only safety statement for a zero-param tool, an agent has everything needed to call and interpret 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 tool takes zero parameters, so the baseline is 4. The schema is empty and the description adds that no preparatory call is needed, which is the relevant semantic context for a parameterless 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?

The description names the specific mechanism (Ed25519-signed tamper-evident hash chain) and resource (audit log), and states the returned status values (intact/broken/cannot_verify). This clearly separates it from siblings like sysknife_get_audit_rules, which read rules rather than verify integrity.

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 explicitly tells the agent that no prior sysknife_plan is required, which is meaningful guidance given the plan/execute workflow among siblings. It stops short of naming alternatives or stating when verification should be skipped, so it falls short of a full when/when-not treatment.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the repeated 'read-only' phrasing adds no new information. The one piece of added value is naming the underlying command with `--long`, which hints at the depth of output returned. No disclosure of output format or failure modes beyond that.

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 line, front-loaded with the action name and the substantive purpose. Minor waste from saying 'Read-only' at the start and 'read-only' at the end, which is redundant with the annotations.

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

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

For a zero-parameter read tool with full annotation coverage and no output schema, the description supplies everything needed to invoke it, plus the concrete CLI command for context. Explaining the return shape would be a nice extra but is not essential 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?

Zero parameters, so the baseline is 4. The description correctly confirms 'no params', matching the empty schema, leaving nothing ambiguous for the caller.

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: show cloud-init provisioning status, with the concrete underlying command `cloud-init status --long`. No sibling covers cloud-init, so it is distinguishable, though it does not explicitly differentiate itself from the many other *_status tools in the family.

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 — an agent can infer to call it when it needs cloud-init provisioning state. There is no explicit when/when-not guidance or reference to an alternative (e.g., general host state via sysknife_get_host_state).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered and the description's 'Read-only' adds nothing. The one genuine contribution is the 500-line cap on the journal output, which is useful behavioral context. Missing are privilege requirements (journal access often needs group membership or root) and whether output is truncated or paginated.

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 short, but the first sentence is largely a tautological restatement of the name and title, and the second is a sentence fragment lacking a verb. The valuable content (journal log, last 500 lines) is present but buried behind name-echo padding.

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 what comes back; 'last 500 lines' does that partially. However, for a zero-param read tool sitting among ~50 siblings including sysknife_get_journal_log, sysknife_get_service_logs and sysknife_doctor, the description never establishes its niche, which is the main thing an agent needs 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 tool takes zero parameters, so the baseline is 4. The description does not need to explain any input, and nothing it says contradicts 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 second sentence does name the concrete resource — the recent system journal log, capped at the last 500 lines — but the leading sentence merely restates the tool name ('Read-only SysKnife action `CollectDiagnostics`'), and the stated purpose (generic diagnostics collection) is broader than the actual behavior (journal read). A sibling named sysknife_get_journal_log exists and is never distinguished, so an agent cannot tell whether this is the same data or a different slice.

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?

'for error diagnosis and troubleshooting' implies a usage context, which is more than nothing. But there is no explicit when-to-use vs when-not, and critically no mention of sysknife_get_journal_log or sysknife_doctor as alternatives — the agent must guess which journal-reading tool to pick.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description's 'read-only' (stated twice) is pure duplication. Beyond that it only says 'no params', which the empty schema already conveys; nothing is added about output shape, error behavior or what a distrobox listing 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?

Very short and front-loaded with the action name followed by the purpose. It loses a little by restating 'read-only' at both the start and the end of a ten-word sentence, which is wasted space at this 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 zero-parameter read tool the description covers the essentials of what it does and that it is safe. However, with no output schema present, the description carries the burden of telling the agent what a listing returns (container names, images, status), and it says nothing about that.

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

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

The tool takes zero parameters, so the baseline is 4. The description confirms 'no params', which is consistent with the empty schema and prevents an agent from hunting for undocumented arguments.

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

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

States a specific verb and resource: 'list distrobox containers', plus the action identifier DistroboxList. The 'distrobox' qualifier meaningfully separates it from sibling listing tools such as sysknife_list_containers, sysknife_list_toolboxes and sysknife_multipass_list, though those siblings are never named.

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 resource name — use it to enumerate distrobox containers — and 'no params; read-only' signals it is a safe discovery call. There is no explicit when-to-use/when-not guidance and no routing to the alternative container-listing siblings, so the agent must infer the choice.

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 burden and does state the key traits: read-only, safe, and that it contacts the daemon (a nonzero-cost probe). It does not say what happens on an unreachable daemon or whether the call can block, leaving a minor gap for a zero-arg health probe.

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

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

One sentence that front-loads the verb and enumerates outputs in scan order, then a safety clause. No filler, nothing redundant.

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

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

An output schema exists, so return values need not be explained, yet the description already names the reported facts (daemon, provider/model, DB path, chain status). For a zero-parameter read-only probe, nothing an agent needs in order to call it 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly keeps its focus on outputs rather than inventing parameter talk.

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 (diagnose) and enumerates exactly what the tool inspects: daemon reachability, brain provider/model, audit DB path, and audit-chain status. That enumeration distinguishes it from neighbors like sysknife_audit_verify and sysknife_collect_diagnostics without opening either schema.

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

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

"Safe to call without prior sysknife_plan" gives a concrete precondition cue tied to the plan/execute workflow, which is the main decision an agent faces. It stops short of explicitly routing away from sysknife_audit_verify or sysknife_collect_diagnostics, so alternatives are only implied by "quick".

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 delivers the single most important behavioral fact: MCP cannot approve its own mutations and a one-time CLI receipt is mandatory. It stops short of describing execution atomicity, partial-failure behavior, or side effects, which remain 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?

Two tight sentences: the action is front-loaded and the gating constraint follows immediately. Nothing is redundant or padded.

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

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

With an output schema present, return values need not be explained, and the description covers the critical approval workflow and the plan-to-execute dependency. Missing only failure/partial-execution semantics for what is inherently a mutating 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% and both the steps array and StepToExecute fields are documented in-schema, so the baseline of 3 applies. The description reinforces the approval_receipt requirement but adds no new semantics about step ordering or passthrough behavior 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?

States a specific verb (Execute) and resource (exact steps produced by sysknife_plan), and explicitly ties the tool to the sibling planner so an agent can distinguish it from the read-only collector tools. The scope — executing plan output, not inspecting state — 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?

Clear prerequisite chain: steps must come from sysknife_plan and each requires a CLI approval receipt before execution. It does not explicitly name 'do not call without a prior plan' or cover alternatives, but the sequencing requirement is strong enough to route the agent correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's repeated 'read-only' adds no new behavioral information; the only real addition is the jail-scoping behavior, and it says nothing about what the status output contains or whether it requires privileges.

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

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

One compact line with the resource stated first and the parameter note trailing, so it is front-loaded and cheap to parse. It loses a point for saying 'read-only' twice in the same sentence, once in the prefix and again as a suffix.

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 no-required-parameter, no-output-schema status read whose annotations already cover safety and idempotency, the definition gives everything needed to invoke it correctly. The only missing element is any hint of what the returned jail status includes, which is minor given the tool's simplicity.

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 declares zero properties (additionalProperties: true), so the description is the only place the optional `jail` argument is surfaced — genuinely useful information an agent would otherwise miss. It stops short of describing the accepted format or values for `jail`, which is the only 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+resource combination ('show fail2ban jail status') that is unambiguous and clearly distinct from neighboring status tools like sysknife_ufw_status or sysknife_get_firewall_state. It does not explicitly name a sibling to contrast with, keeping it just below 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 'omit for all jails' note gives concrete guidance for the single scoping decision, but there is no statement of when to reach for this tool versus the many other firewall/security status siblings. Usage is implied by the tool's domain rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the two 'read-only' mentions in the description are pure repetition. The one piece of added value is disclosing the apt-cache policy backing, which hints at the shape of the output. It says nothing about whether elevated privileges are needed or how a missing package argument behaves.

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?

Very short and front-loaded with the verb and resource. The trailing 'read-only' duplicate and the quoted internal action name add minor noise but nothing substantial.

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 read-only inspection tool with annotations covering safety and no output schema, the description is nearly sufficient: it names the resource and the underlying command. It falls short only on argument behavior and privilege requirements.

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 declares no properties (additionalProperties: true), so the description's note that 'package' is an optional argument is genuine added value. However, it gives no format or matching semantics for that argument, nor does it say what is returned when the argument is omitted (presumably all pins).

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 action (show apt pin priorities) and even names the underlying mechanism (apt-cache policy), which tells an agent exactly what data comes back. It is distinguishable from siblings like sysknife_apt_show or sysknife_apt_list_installed, though the differentiation is implicit rather than stated.

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 guidance on when to choose this over sysknife_apt_show, sysknife_apt_list_upgradable, or other apt siblings, and no mention of when pin data is relevant (e.g. debugging held-back upgrades). The only qualifier is 'read-only', which is not 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?

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable operational context beyond that: it requires auditd to be installed and maps to `auditctl -l`. It does not describe what happens if auditd is missing, but the extra prerequisite disclosure is meaningful.

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 compact and front-loads the action and command. There is slight redundancy in repeating 'read-only' and restating the tool name in 'Read-only SysKnife action `GetAuditRules`', but the total length is appropriate.

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

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

For a zero-parameter, read-only listing tool whose safety profile is covered by annotations, this is largely complete: it names the command and the auditd prerequisite. Without an output schema, it could say more about the return format, but no critical calling information 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?

With zero parameters and 100% schema coverage, the baseline is 4. The description confirms 'no params', which aligns with the schema, though there is no parameter detail to add.

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 ('list') and resource ('loaded audit rules') and even names the underlying command (`auditctl -l`), so the purpose is immediately clear. It does not explicitly distinguish itself from the related sibling `sysknife_audit_verify`, which is the only gap keeping it from a 5.

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

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

It states a prerequisite ('needs auditd installed') and says 'no params', which is useful context for calling it. However, it gives no explicit guidance on when to choose this over alternatives like `sysknife_audit_verify`, leaving usage implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructiveness, and a closed-world scope, so the description's 'Read-only' line is redundant. It adds nothing about access requirements, error behavior when the user doesn't exist, or what the returned key data looks like.

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?

Compact and front-loaded: the operation and the key parameter come first. The leading 'Read-only SysKnife action `GetAuthorizedKeys`.' restates the tool name and is largely wasted space, but the total length is not excessive.

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 read-only lookup with full annotation coverage and no output schema, the essentials are present. It still omits permission requirements and the shape of returned key entries (key type, comment, fingerprint), which an agent may want before calling.

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 declares no properties (additionalProperties: true, 0 params), yet the description names a required `username`. That is the only real added semantic value, but it conflicts with an empty schema and it doesn't say whether the username must be a local account or what format is expected.

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

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

States a specific verb and resource: 'list SSH authorized_keys for a user'. The resource is distinct from the many status/list siblings, so an agent can pick it out without opening the schema. It lacks explicit sibling differentiation (e.g., vs. get_sudo_grants or get_password_aging), keeping it at 4.

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?

No indication of when to use this versus alternatives, no prerequisites (e.g., whether root is needed to read another user's keys), and no exclusions. The only hints are the implied per-user scoping and the 'read-only' label.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so repeating 'read-only' adds little. The one genuinely additive item is the prerequisite 'needs certbot installed', but the description says nothing about what happens when certbot is absent, what fields certificates carry, or how expired certs are reported.

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 and short, with the resource named in the first clause. Minor waste from saying 'read-only' twice, once in the action prefix and again as a trailing clause that the annotations already cover.

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 parameterless, non-destructive read with full annotation coverage and no output schema, the description supplies everything needed to decide to call it: what it lists and the certbot dependency. Only the failure behavior / return shape is left implicit, which is a small residual 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?

Zero parameters, so baseline is 4. The description confirms 'no params', which matches the permissive object schema and removes any doubt about whether arguments are expected.

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 concrete verb (list) and resource (certbot-managed certificates), plus the namespaced action `GetCertificates`, so an agent can tell exactly what it returns. It is distinguishable from the many sysknife status/list siblings by its certbot-specific scope, though it never names a sibling to route away from.

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

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

It states the operational context clearly: no parameters are needed and certbot must be installed, which is the key precondition for a meaningful call. There are no exclusions or explicit alternatives, but the resource is unique enough among siblings that none is strictly required.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description only repeats 'read-only' and adds 'Podman container'; it says nothing about return contents, permission requirements, or failure behavior beyond what annotations provide.

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

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

It is a compact, front-loaded sentence with no filler. The trailing 'params: username*, name*' notation is cryptic but does not bloat the description.

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

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

There is no output schema, yet the description never explains what inspect returns. Combined with the empty input schema and the unsupported parameter claims, an agent lacks enough information to invoke this 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 description claims required parameters 'username*' and 'name*', but the input schema defines no properties at all. That is a significant mismatch: the description invents parameter expectations that the schema does not support, and it gives no meaning or format for either value.

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

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

The description uses a specific verb, 'inspect', and resource, 'Podman container', so an agent can tell this is a single-container inspection tool rather than the sibling list operation. It is clear, but it does not explicitly differentiate itself from sysknife_list_containers.

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: use this to inspect a specific Podman container. However, it never says when to choose this over sysknife_list_containers, how to discover a container name, or what prerequisites are needed.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the description's 'read-only' adds little. It does add the underlying source (timedatectl), which tells the agent what data is read, but nothing about failure modes or output shape.

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

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

One compact line with the action name and return contents front-loaded. No filler, though the backticked action name is somewhat redundant with the tool 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?

For a trivial no-arg read tool with full annotations, the description covers enough: it names the returned fields and the data source. No output schema exists, but the enumerated fields effectively describe the return.

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

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

Zero parameters, so the baseline is 4; 'no params' explicitly confirms the tool takes no arguments and can be invoked directly.

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+resource: reads current date, time, timezone and NTP status via timedatectl. It is clearly distinct from siblings like get_network_status or get_host_state, though it does not explicitly differentiate itself.

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?

No guidance on when to call this versus related status tools (host_state, network_status, resolvectl_status). Usage is only implied by the tool's name and 'no params' remark.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by naming the underlying command (df -h), which tells the agent the output is human-readable per-filesystem usage — context the annotations don't provide. It still doesn't mention pagination, truncation, or output format beyond the analogy.

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?

Short and front-loaded, with the read-only qualifier and the (df -h) anchor arriving immediately. Slightly redundant phrasing ('Read-only ... — no params') that repeats what the schema/annotations already establish.

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

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

For a zero-parameter, read-only inspection tool with full annotation coverage and no output schema, the description gives enough to call it correctly and know roughly what returns. What's missing is only differentiation from adjacent disk/mount inspection 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?

Zero parameters, so the baseline of 4 applies. The explicit 'no params' statement is consistent with the empty schema and sets accurate expectations.

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: 'show disk space usage for all mounted filesystems (df -h)'. The df -h analogy makes the exact scope and output style concrete. It doesn't explicitly distinguish itself from siblings like get_mounts or get_lvm_report, 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?

There is no when-to-use guidance and no mention of alternatives, even though get_mounts, get_lvm_report, and get_host_state overlap in the filesystem/disk domain. The 'read-only ... no params' note describes the tool but does not route the agent among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description earns credit for what it adds beyond that: a scope statement (three backends probed) and the interpretive warning that an unavailable or inactive frontend is not evidence of an unfiltered host. It does not describe the shape or failure modes of the returned observations.

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 line, front-loaded with the action name and the resource scope before the caveat about inactive frontends. Slight redundancy in restating 'read-only' twice (in the opener and again as a fragment), but no sentence 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?

For a parameterless read tool with no output schema and full annotation coverage, the description covers scope, safety, and the main interpretive pitfall. The remaining gap is return-value shape — an agent is not told what a 'backend state' observation looks like per frontend — but that is a modest omission given the tool's simplicity.

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

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

Zero parameters, and the description confirms this explicitly with 'no params', which matches the empty schema. The baseline for a parameterless tool applies and nothing is left ambiguous.

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

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

It names the concrete sources it inspects (nftables, ufw, firewalld observations), so an agent knows this aggregates multiple firewall backends rather than a single one. The verb 'inspect' plus the explicit backend list is specific. It stops short of 5 because it never distinguishes itself from the sibling tools sysknife_get_firewall_state, sysknife_ufw_status, or sysknife_get_nftables_ruleset, which read like overlapping resources.

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?

'Use for general firewall status' is a when-to-use signal, and the caveat that unavailable/inactive frontends do not prove the host is unfiltered gives useful interpretation guidance. But it gives no contrast against the very similarly purposed sibling sysknife_get_firewall_state, so an agent cannot reliably choose between them from this text. Selection guidance is implied rather than comparative.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so restating 'Read-only' adds little. The description does add useful scope detail about what state is surfaced and confirms there are no parameters, but it says nothing about privilege requirements or behavior when firewalld is absent/stopped.

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 that front-loads the read-only nature and then the scope. The 'SysKnife action `GetFirewallState`' naming is mildly redundant with the tool name, but overall there is no wasted 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?

For a zero-parameter read tool with full annotation coverage and no output schema, the description covers what is returned conceptually. Minor gaps remain around privileges and behavior on non-firewalld systems, but nothing blocks 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?

This tool takes zero parameters, which is the baseline-4 case, and the description reinforces it with 'no params' so an agent won't hunt for inputs. Nothing further is needed because there is nothing to parameterize.

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 concrete verb ('show') and a specific resource set: firewalld zones, open services, and port rules. Naming firewalld implicitly separates it from siblings like ufw_status, get_nftables_ruleset, and get_firewall_backend_state, but it never states that routing rule 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 only implied by the 'firewalld' scoping — an agent can infer this is the tool for firewalld systems, but there is no explicit when-to-use or when-to-prefer-a-sibling guidance, e.g. versus sysknife_ufw_status or sysknife_get_firewall_backend_state.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description's 'Read-only' prefix is largely redundant. The one piece of added context is that the target must already be installed (no remote lookups), but nothing is said about what happens for a non-installed app_id or what the metadata payload 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?

A single compact line that front-loads the action and the resource, then the parameters. The internal code-name 'GetFlatpakAppInfo' is mildly redundant with the tool name but costs little.

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 should indicate what 'metadata' means (version, runtime, origin, permissions), since that determines whether an agent calls this or list_installed_flatpaks. It also leaves the mismatch between the declared params and the empty schema unexplained, so an agent must guess how to pass arguments.

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 is an empty object with additionalProperties=true, so the description is the only place that names the two real arguments `username*` and `app_id*` and marks both required. That is genuinely additive, though it gives no format hints (e.g. reverse-DNS app id form) or scope constraints on username.

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

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

Specific verb+resource: 'show metadata for an installed Flatpak', with the underlying action name GetFlatpakAppInfo. The word 'installed' distinguishes it from siblings like sysknife_search_flatpak_apps and sysknife_list_flatpak_remotes, though it never names those 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 only implied: 'for an installed Flatpak' plus a required app_id signals this is a per-app lookup rather than a listing, but there is no explicit when-to-use versus list_installed_flatpaks or search_flatpak_apps, and no stated prerequisites or failure cases.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the 'Read-only' restatement earns nothing. What does add value is the disclosure of the actual returned content (hostnamectl identity fields), which compensates for the absence of an output schema. No mention of privilege requirements or fallback behavior if hostnamectl is unavailable.

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

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

Two compact sentences with no filler, and the returned-field list is front-loaded after the action name. The phrasing is grammatically awkward ('what this host is:') and a fragment, but it doesn't cost comprehension or 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 zero-parameter, read-only, annotation-covered tool with no output schema, the description supplies enough: it says what data comes back and how it differs from the system-state read. The only gap is the missing sibling-relative guidance, which is minor at this complexity.

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

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

The tool takes zero parameters, so there is nothing to mis-specify and the baseline of 4 applies. The description correctly implies a no-argument, whole-host read.

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 precisely and enumerates what it returns (OS release, kernel, architecture, virtualization, machine identity via hostnamectl), which is far more informative than the bare action name `GetHostState`. It also distinguishes itself from GetSystemState, though that tool is not among the siblings, so the differentiation against actual siblings in this set is weaker.

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 'what this host is' framing and by the contrast with GetSystemState ('reports deployments an apt host does not have'), which tells the agent this is the host-identity read for apt hosts. However, no explicit when-to-use/when-not guidance is given relative to the surrounding status tools, and the named alternative isn't in the sibling set.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description merely repeats 'read-only' three times rather than adding new behavioral facts. It does contribute the journalctl backing, the JSON return format, and the 100/10000 line bounds, but omits whether elevated privileges are needed or how output is truncated.

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 parameter enumeration is front-loaded and efficient, but the string is one long semicolon-chained sentence that repeats 'read-only' at both ends and buries the trailing 'read-only' as redundant noise. Trimming the duplicated safety claim would tighten it with no loss.

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 at least names the return shape (JSON) and gives every argument with formats and defaults, so an agent can call it correctly. It stops short of describing the JSON fields returned or ordering of entries, which leaves a small gap for a log-reading 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?

The input schema is an empty object with additionalProperties, so the description is the sole documentation of the arguments — and it covers unit, priority (numeric, name, and range forms), boot, kernel, since/until with example syntax, grep regex, and lines with default and cap. That is exactly the compensating detail the schema lacks.

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 — read filtered systemd journal entries as JSON via journalctl — which is far more informative than the name alone. It does not, however, distinguish itself from the sibling sysknife_get_service_logs, which reads logs for a specific unit, so an agent must infer the boundary.

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?

'All params optional' plus a default of 100 lines implies a general-purpose journal reader, but there is no explicit when-to-use or when-not-to-use guidance. The obvious alternative (sysknife_get_service_logs) is never named, so routing between the two is 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description's repeated 'read-only' adds nothing. The one piece of real added value is disclosing the backing command (ss -tulpn), which implies output shape; it does not mention that process/PID columns may be incomplete without root privileges.

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?

Single compact sentence with the operation and scope front-loaded before the example query. It wastes a few words restating 'read-only' twice (once in the wrapper and once in the list), which keeps it just short of maximal.

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

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

For a zero-parameter read tool with rich annotations and no output schema, the description gives enough to call it correctly. The only gap is output expectation — whether it returns a socket table and whether privileged process names appear — which would help an agent interpret results.

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

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

Zero parameters, so the baseline is 4, and the description correctly and explicitly says 'no params', removing any doubt about needing a port argument. Nothing further is required here.

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 — 'show listening TCP/UDP sockets and the process bound to each' — plus the underlying command (ss -tulpn), which pins the scope precisely against siblings like list_processes or get_network_status. It never names an alternative explicitly, so the differentiation is inferable rather than stated.

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?

'use for "what is listening on port X?"' gives one concrete triggering question, which is genuinely actionable. However there are no when-not conditions and no sibling is named as the alternative for broader network or process questions, so routing is left partly to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, but the description adds the key non-obvious trait: the tool actually invokes logrotate in debug mode, so it is a simulation that makes no changes. That is real context beyond the annotations; only the required privileges and output shape are unstated.

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 front-loads the read-only guarantee and the dry-run behavior. Slightly dense with backticks and dashes, 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?

For a simple read-only inspection tool with no output schema, the description covers the essential behavior and the optional parameter. Missing only privilege requirements and rough output expectations, which is a minor gap at this complexity.

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 declares no properties, yet the description supplies the one meaningful input — an optional `config` path — which the structured schema does not carry. It could have said what happens when config is omitted (default logrotate config), but it adds genuine value over an 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?

Names the specific action (GetLogrotateStatus) and explains it concretely as a dry-run of logrotate (-d) that shows what would rotate. Verbs and resource are unambiguous and clearly distinguishable from status siblings like sysknife_get_service_status or sysknife_ufw_status.

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 read-only framing implies a diagnostic/inspection use case, but it never states when to pick this over alternatives (e.g., journal logs) or any prerequisites such as needing logrotate installed or root. Usage is inferred 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so repeating 'read-only' twice in the description adds nothing. What little extra it provides is the JSON output format and the fact it wraps lvs; there is no disclosure of error behavior or output shape details.

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 short, front-loaded sentence with the action and resource first. It loses a point for redundancy: 'Read-only' at the start and 'read-only' at the end say the same thing, and both duplicate the annotations.

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

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

For a zero-param read-only tool with full annotation coverage and no output schema, the description supplies what matters: the exact resource, the fields in the returned JSON, and confirmation that no arguments are needed. Nothing required to invoke it correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case, and the description explicitly confirms 'no params' so the agent knows an empty object is a valid call. There is nothing further to disambiguate.

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

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

States a specific verb (list) and resource (logical volumes) plus the fields returned (VG, size, attributes, usage) and the underlying mechanism (lvs). The resource is clearly distinct from sibling read tools like sysknife_get_disk_usage and sysknife_get_mounts, so an agent can select it 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?

Usage is only implied: an agent infers it should call this when it needs LVM volume inventory. The note 'no params' usefully signals a zero-argument call, but no alternatives or when-not-to-use conditions (e.g., vs get_disk_usage) are named.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description usefully adds the output analogy '(free -h)', giving the agent a concrete sense of the returned format without an output schema.

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

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

One compact line that front-loads purpose, notes read-only, and states the free -h output form with zero 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 a simple no-arg read tool with annotations covering safety, the description plus the free -h reference give enough for correct invocation. Only minor gap is absence of explicit sibling disambiguation.

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

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

Zero-parameter tool, baseline 4; the description confirms 'no params', consistent with the empty schema. Nothing further is needed.

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

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

States a specific verb+resource: 'show RAM and swap usage', which clearly distinguishes it from disk-usage or host-state siblings. It lacks explicit differentiation from a broader sibling like sysknife_get_host_state, 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 description implies when to call it (wanting memory/swap stats) and notes 'no params', but gives no explicit when-to-use/when-not guidance or alternatives against overlapping siblings such as sysknife_get_host_state.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered — the description's repeated 'read-only' adds nothing. What it does add is the underlying command (findmnt) and the JSON output shape, which gives a rough idea of return structure.

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 short sentence with the action and purpose front-loaded, so an agent can decide quickly. Minor waste in restating 'read-only' twice, once at the start and again at the end.

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-param, read-only inspection tool with complete annotations and no output schema, the description gives enough to call it correctly and understand the output source. Only a richer hint on returned fields would push it higher.

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

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

Zero-parameter tool, so the baseline is 4. The description explicitly confirms 'no params', which matches the empty schema and removes any ambiguity about required input.

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

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

States a specific verb and resource — 'list mounted filesystems as JSON (findmnt)' — which is unambiguous about what the tool returns. It does not name a sibling or explain how it differs from the close neighbor sysknife_get_disk_usage, so it stops short of full differentiation.

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

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

'no params; read-only' implies a safe, invocation-simple lookup, but there is no explicit when-to-use guidance and no routing against related tools like get_disk_usage or get_lvm_report. The agent must infer the choice of mounts-over-disk-usage from the description 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?

Annotations already declare read-only, idempotent, non-destructive, and not open-world behavior. The description adds useful context that this reports LIVE runtime state rather than saved config, and it lists the categories of state returned. It does not describe output formatting or permission requirements, but those gaps are minor for a no-param read-only status 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 description is compact and front-loaded with the action and scope. Every clause adds useful differentiation, especially the live-vs-saved-config distinction and the named alternative.

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 no-param read-only status tool with no output schema, the description provides enough: what it reports, that it is live/runtime, that it is read-only, and which alternative handles saved config. Nothing essential is missing for correct invocation.

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

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

The tool has zero parameters, so the baseline is 4. The description reinforces that there are no params, which is consistent with 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?

States a specific read action and precisely defines its scope: live network state including interfaces, IP addresses, and connection state. It explicitly distinguishes runtime status from saved configuration, which separates it from sysknife_netplan_get_config.

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 that this tool takes no parameters and is for live runtime status, not saved configuration. It names the appropriate alternative for saved Ubuntu network config, making the when-to-use boundary explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so restating 'read-only' adds nothing. The one piece of genuine added value is the warning that the ruleset does not by itself prove traffic is blocked, which guides interpretation; nothing is said about output shape or ordering, but the lower bar applies given full annotation coverage.

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

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

Two short clauses, front-loaded with the action semantics, with zero wasted preamble. Minor redundancy in repeating 'read-only' twice (once in the opener, once in the list) keeps it just below top marks.

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 no-param, no-output-schema read of a self-describing resource, the description covers what an agent needs plus an interpretive caveat. The only gap is that it does not explain the returned ruleset's form, which would help since no output schema exists.

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

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

The tool takes zero parameters and the description confirms 'no params', which is consistent with the schema and leaves nothing to infer. Baseline 4 for a zero-parameter tool 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?

Names a specific verb and resource – 'read the current nftables ruleset' – so an agent knows exactly what it retrieves. It does not, however, distinguish itself from close siblings like sysknife_get_firewall_state, sysknife_get_firewall_backend_state, or sysknife_ufw_status, leaving ambiguity about which firewall view to call.

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: 'no params; read-only' tells the agent it is safe to call, and the caveat about rules not proving traffic is blocked hints at when the output is useful. There is no explicit statement of when to prefer this over the sibling firewall state 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'read-only' repeated twice in the description adds nothing. The one genuinely additive detail is the underlying 'chage -l' invocation, which tells the agent the read is local and what fields to expect; no mention of permission requirements or error behavior when the user does not exist.

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?

Single short line, front-loaded with the action name and followed by the effect, the backing command, and the parameter. The duplicated 'read-only' tag is mild waste but the whole definition is under 25 words with zero 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, naming 'chage -l' carries most of the return-value burden for the agent. However, the definition leaves an unexplained gap between the declared required 'user' parameter and the empty input schema, and says nothing about failure modes for unknown accounts.

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 is an empty object with additionalProperties=true, so the description is the only place the required 'user' argument is documented — genuinely additive beyond structured data. It is slightly weakened by the 'user*' shorthand and by not stating the expected format (username vs UID) or reconciling with 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?

States a specific verb+resource ('show a user's password-aging fields') and names the exact underlying command (chage -l), which pins down the data returned. No sibling tool covers password aging, so the scope is unambiguously distinct.

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 by the purpose: inspect password expiry for a given account. There is no statement of when to prefer this over sibling read tools (e.g. list_users, get_sudo_grants) and no prerequisites such as needing root or a target account to exist.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the 'recent' qualifier and the journald source; it does not say how much log history is returned or what happens for a stopped/unknown unit.

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

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

Two short sentences, with the action and purpose front-loaded before the parameter note. The 'param: unit*' shorthand is terse to the point of being cryptic, 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 an empty input schema, the description is the only source of parameter and return-shape information, and it omits unit-name format, log window/line count, and behavior on missing units. The mismatch between 'param: unit*' and the parameterless schema is left unresolved.

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 declares zero parameters (additionalProperties: true), yet the description asserts a required 'unit*' argument, leaving the agent unsure whether to pass anything. It names the parameter but gives no format (bare name vs. name.service) and no indication of valid values.

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: 'fetch recent journald log lines for a service', scoped to a single service. This is clearer than the name alone and hints at the difference from the broad sibling sysknife_get_journal_log, but does not explicitly contrast the two.

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?

No guidance on when to use this versus sysknife_get_journal_log, sysknife_get_service_status, or sysknife_collect_diagnostics, and no preconditions such as journald access or elevated privileges. The only usable cue is 'for a service', which the agent must infer.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so the description's repeated 'read-only' adds nothing new. It does add useful context by disclosing the underlying mechanism (systemctl show) and the specific values returned, but it says nothing about failure modes when the unit doesn't exist or about permission requirements.

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

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

One compact sentence with the action name, output fields, mechanism and parameter all front-loaded; nothing bloated. The trailing '— read-only' repeats the opening 'Read-only', which is minor redundancy.

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

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

For a simple read-only inspection tool with full annotation coverage and no output schema, the description supplies the essential missing pieces: which fields are returned and the underlying command. The only real gap is the inconsistency between the claimed required 'unit' parameter and the empty 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?

The input schema is an empty object with additionalProperties:true, so the description is the only place that documents the 'unit' parameter and marks it required ('unit*'), which is genuinely valuable. However, it conflicts with the reported zero-parameter schema, leaving an agent uncertain whether unit is a formal property or an unvalidated pass-through.

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 ('GetServiceResourceLimits' showing a service's cgroup limits') and lists the exact fields returned (MemoryMax/CPUQuota/TasksMax), which distinguishes it from the broader sysknife_get_service_status. It does not explicitly name the sibling it competes with, so a 4 rather than 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 only implied: an agent can infer this is the tool for cgroup limit inspection as opposed to general service status. There is no explicit when-to-use/when-not-to-use statement or pointer to alternatives like get_service_status or get_memory_info.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description's 'Read-only' merely restates it. It adds no detail on what 'detailed status' contains (active state? PID? exit codes?) or whether it errors on unknown/ambiguous units, which is the real behavioral 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?

Very short and front-loaded, with the required parameter flagged by the asterisk. The leading 'Read-only SysKnife action `GetServiceStatus`' restates the tool name and annotation and earns little.

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 read tool with no output schema this is close to adequate, but the schema/description mismatch (empty schema vs. a required 'unit' param mentioned only in prose) and the absence of any detail on the returned status fields leave an agent unsure what to pass and expect.

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 declares no properties, so the description's 'param: unit*' is genuinely additive — it reveals the required argument name that the schema omits. However, it does not say what form a unit takes (e.g., 'nginx.service' vs 'nginx') or whether a full name is required, leaving format semantics 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 verb+resource: 'show detailed status of a service'. An agent can distinguish this from sysknife_list_services (enumeration) reasonably well, though the description never names those siblings 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?

No statement of when to use this versus sysknife_list_services, sysknife_get_service_logs, or sysknife_get_service_resource_limits. 'Read-only' implies a safe inspection call but provides no selection guidance or preconditions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so repeating 'read-only' twice adds nothing. The one genuine addition is the scope of what gets listed (only SysKnife-managed sudoers.d drop-ins, not the main sudoers file), but return format and volume are unstated.

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?

Very short and front-loaded with the operation and target. It wastes a little space restating 'read-only' at the end after already saying it at the start, and echoing the internal action name adds no 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?

For a no-param, read-only list operation with full annotation coverage, the description gives enough to call it correctly and understand the scope of results. It could note what a returned grant entry looks like, since there is no output schema, but nothing critical 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?

Zero-parameter tool, so the baseline is 4; the description correctly reinforces 'no params', which removes any doubt about needing arguments despite the permissive additionalProperties 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 (list) and resource (SysKnife-managed sudoers.d drop-ins), which is more precise than the name alone. The 'SysKnife-managed' qualifier scopes the result set and helps distinguish it from generic user/key inspection siblings, though it doesn't name a specific alternative.

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: 'read-only' and 'no params' signal a safe inspection call, but there is no statement of when to reach for this tool versus sysknife_get_authorized_keys or sysknife_list_users, nor any exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is fully covered; the description's repeated 'read-only' adds nothing. The one piece of genuine behavioral content is 'omit to dump all', which tells the agent the default scope of the call. No information about output shape or failure modes.

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 short and front-loaded, but it wastes space on redundancy: 'Read-only SysKnife action GetSysctl' and the trailing '; read-only' restate the same fact twice and echo the tool name. Stripping that duplication would leave a tighter, more informative sentence.

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 single-purpose read tool with no output schema, the definition covers purpose, the optional key parameter, and the no-key default. The main omission is what the returned data looks like (single value vs. full sysctl table), which the agent must infer from 'dump all'.

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

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

The input schema declares no properties at all (additionalProperties: true), so the description is the only source of parameter information — and it delivers: it names `key`, marks it optional, gives the dotted format with a concrete example ('net.ipv4.ip_forward'), and explains the omit-to-dump-all semantics. That is substantial added meaning over an 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?

States a specific verb and resource: 'read a kernel parameter (sysctl)', which clearly separates it from the many other sysknife_get_* siblings that read different resources (disk usage, memory, mounts, etc.). The dotted-key example makes the resource concrete, though it never explicitly contrasts itself with any named sibling.

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 does give one real usage rule: pass a dotted key to read one parameter, or omit it to dump all. That is implied guidance for the two modes, but there is no mention of prerequisites, permissions, or when another tool (e.g. sysknife_get_host_state) would be preferable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the repeated 'read-only' phrasing adds nothing new. The genuinely useful addition is the data source path (/etc/default/grub), which tells the agent where the value comes from and that it is a local openWorldHint=false read; no return format or failure modes are described.

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

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

A single short line with the key fact (what is read, from where) up front. Minor waste from stating 'read-only' twice and restating the tool name, but nothing that harms comprehension.

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 trivial parameterless read with no output schema, the description supplies the resource, scope, source file, and safety posture. The only gap is the shape of the returned value (raw string vs parsed key/value), which is minor for such a simple action.

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

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

Zero-parameter tool, so the baseline is 4. The description explicitly confirms 'no params', matching the empty schema, so there is nothing left ambiguous.

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 pair ('read current GRUB_CMDLINE_LINUX') and names the exact file it reads, so the agent knows precisely what it gets. The leading 'SysKnife action `GrubGetKargs`' restates the tool name, but the second clause disambiguates fully. No sibling tool covers GRUB kernel args, so it is distinguishable in context.

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?

Says 'no params; read-only', which implies it is safe to call freely, but gives no explicit when-to-use/when-not-to-use guidance or mention of alternatives (none exist among siblings). Adequate but minimal.

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 read-only safety and that no prior plan is needed, which are key traits. However, it omits ordering (e.g. most recent first), pagination behavior beyond limit, retention or permissions, leaving meaningful gaps for a mutation-free but audit-oriented list 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?

Three compact sentences, front-loaded with purpose and safety, then filters, then return shape. Every sentence contributes directly to correct invocation, with 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?

Given a simple read-only list tool with an output schema and full parameter documentation, the description provides the essential context: safety, plan-independence, filter set, and return container. Only minor details such as ordering and retention are missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters with examples. The description restates the filters and adds 'canonical action name' and the default limit of 20, but adds little beyond what the schema already provides. 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 and resource: 'List past SysKnife audit-log entries.' This is clearly distinct from sysknife_apt_history_list (APT history) and sysknife_audit_verify (verification), though no sibling is named explicitly. The purpose is unambiguous 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?

Explicitly says it is 'Read-only and safe to call without prior sysknife_plan,' which gives a clear condition relative to a critical sibling. It does not explain when to prefer this over sysknife_audit_verify or apt history, but the primary usage context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered upstream and 'Read-only' in the description is largely redundant. What the description does add beyond annotations is that the listing is scoped per-user, but it says nothing about what happens if the user has no containers, whether the user must exist, or what the result looks like.

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

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

Two short clauses, with the action name and the core purpose front-loaded ahead of the parameter note. The `param: username*` fragment is terse to the point of terseness, 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 annotations present and no output schema, the safety and return-shape burden is partly lifted, and the parameter hint covers the biggest hole in the empty schema. Still, for a tool whose schema fails to declare its own parameter, the description should say more about username format and scope (rootless vs root containers) than three trailing words.

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

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

The input schema declares no properties at all (additionalProperties: true), so without the description an agent would have no idea what to send. The description compensates by flagging `username` as the (required, per the asterisk) input. It still doesn't explain the expected form of the username or whether it must be the invoking user, which keeps it below 5.

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

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

States a specific verb (list) and resource (Podman containers) with a scope qualifier (for a user), and the word 'Podman' implicitly distinguishes it from the container-adjacent siblings like sysknife_distrobox_list, sysknife_list_toolboxes and sysknife_get_container_info. It does not explicitly name those alternatives, but an agent can map the resource correctly.

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?

'Read-only' hints at the safe-inspection context, but there is no explicit when-to-use guidance, no statement of when to prefer sysknife_get_container_info (detail) over this (enumeration), and no exclusions. The agent must infer selection from the tool name 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's 'Read-only' merely restates readOnlyHint and adds nothing about output shape, whether system and per-user remotes are both included, or permission needs.

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?

Very short and front-loaded, but the opening clause 'Read-only SysKnife action `ListFlatpakRemotes`' repeats the tool name and the readOnlyHint annotation, spending words on no new 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 simple zero-parameter read tool with rich annotations and no output schema, the description is minimally adequate. However, the stray 'username*' mention without schema backing and the absence of any note on what a 'remote' entry contains leave small but real gaps.

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

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

The schema declares no properties, so the baseline is 4, but the description introduces 'param: username*' — a parameter that does not appear in the schema and whose asterisk implies required, contradicting 'Required parameters: 0'. This adds a hint about scoping remotes by user, but the inconsistency muddies rather than clarifies.

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

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

States a specific verb and resource: 'list configured Flatpak remotes'. An agent can distinguish it from siblings like sysknife_list_installed_flatpaks (installed apps) and sysknife_search_flatpak_apps (search) without opening schemas. It does not explicitly name those siblings, keeping it at 4.

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?

No when-to-use or when-not-to-use guidance, and no alternatives are named. The verb 'list' implies a read operation, but the agent must infer that this is for inspecting remote repositories rather than installed apps.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so "Read-only" largely restates structured data. The one genuine addition is the scope limit (local groups only, not directory-backed), but nothing is said about privilege requirements or what the returned records contain.

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?

Very short and front-loaded, with the read-only safety note first and the scope second. The internal action name `ListGroups` is immediately paraphrased by "list all local groups", which is mildly redundant but costs almost nothing.

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

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

For a zero-parameter, closed-world read tool with no output schema, the definition covers what matters: it reads, needs no input, and returns all local groups. Only minor gaps remain, such as whether elevated privileges are required or what fields each group carries.

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

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

There are zero parameters, which establishes a baseline of 4. The description's "no params" simply corroborates the schema; no additional parameter meaning is needed or expected here.

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 ("list all local groups") with an explicit scope qualifier ("local"), which makes it plainly distinguishable from siblings like sysknife_list_users or sysknife_get_sudo_grants by resource. It does not explicitly name or contrast any sibling, which keeps it at 4 rather than 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 only implied: "list all local groups" plus "Read-only" tells an agent this is an inspection call with no arguments. There is no statement of when to prefer it over adjacent tools (e.g. group membership vs. sudo grants), no preconditions, and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only' is pure repetition. Beyond that, the description adds nothing about scope, what 'for a user' means in practice (all users vs. current user), or any output/pagination behavior for a listing that could be long.

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

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

Two short clauses, front-loaded with the action name and effect, with no filler. Slightly hurt by the dangling 'param: username*' fragment whose asterisk notation is unexplained.

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 and no annotations-only relief for the listing semantics; the description neither explains the return shape nor resolves which sibling lister to pick. Given a cluster of Flatpak-related siblings, this is not sufficient to call the tool 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?

The description asserts 'param: username*' as required, but the input schema declares zero parameters (additionalProperties: true, no properties). This is misleading rather than additive: an agent told to pass a required username will find no such field defined.

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: 'list installed Flatpak apps for a user'. However, it does not distinguish itself from the close sibling sysknife_ubuntu_list_flatpaks or from sysknife_list_flatpak_remotes, which an agent must otherwise infer by name 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?

No guidance on when to use this vs. sysknife_ubuntu_list_flatpaks (also a Flatpak lister) or sysknife_get_flatpak_app_info (single-app detail). 'Read-only' implies safety but not selection criteria; the one differentiating hook (per-user scope) is buried in the param fragment.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description's added value is limited to confirming read-only and stating that results include CPU and memory usage; it says nothing about pagination, result caps, or sort order.

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

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

One compact sentence with the operation front-loaded and zero waste. The backtick-quoted internal action name is mildly noisy but harmless.

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-param read tool with no output schema, the definition covers purpose, safety (via annotations), and the shape of the returned data. Only minor gaps remain around result ordering or size, which are low-stakes 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?

Zero parameters, so the baseline is 4. The description explicitly states 'no params', which matches the schema and removes any ambiguity about needing arguments.

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

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

States a specific verb ('list') and resource ('running processes') plus the payload returned (CPU and memory usage), which is enough to separate it from siblings like sysknife_get_memory_info or sysknife_list_services. It does not explicitly name a sibling it is distinct from, 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 only implied by 'Read-only SysKnife action' and 'no params' – an agent can infer this is the go-to call for a process list, but there is no explicit when-to-use/when-not or alternative named (e.g. vs. get_host_state or collect_diagnostics).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description reinforces read-only and adds that output covers all units and their active/enabled state, but does not disclose ordering, pagination, or failure behavior. With annotations carrying the safety burden, this is adequate but not rich.

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

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

Two short clauses, front-loaded with read-only status and scope. The 'SysKnife action ListServices' clause partly restates the tool name, a minor redundancy, but overall it is 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 a zero-param listing tool with no output schema, the description gives enough scope and output content to call it correctly. It could mention result ordering or format, but the omission is minor given the tool's simplicity.

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

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

The tool has zero parameters, so the baseline is 4. The phrase 'no params' matches the schema but adds no meaning beyond it.

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

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

States a specific verb (list) and resource (all systemd units) plus the returned fields (active/enabled state), which distinguishes it from get_service_status (single service) and list_timers. It does not explicitly name those alternatives, so it falls short of a clean 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?

Provides no when-to-use or when-not-to-use guidance relative to get_service_status, list_timers, or other listing siblings. Only the read-only context and 'no params' are given, leaving tool selection largely to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is fully covered. The description adds the useful behavioral detail that results include the next trigger time, but says nothing about ordering, disabled timers, or volume of output.

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 that front-loads the read-only nature and the resource. The leading 'Read-only SysKnife action ListTimers' partially restates the tool name and the readOnlyHint annotation, which is mild redundancy.

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

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

For a parameterless read-only listing with no output schema, the description covers what the tool does and the key returned field (next trigger time). Nothing essential is missing, though notes on disabled timers or result ordering would round it out.

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

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

Zero parameters, so the schema carries no semantic burden and the description correctly notes 'no params'. Baseline 4 applies for a parameterless 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?

The description states a specific verb and resource ('list all systemd timer units') and adds the scope detail of the next trigger time, which distinguishes it from generic service-listing siblings. It stops short of explicitly naming sysknife_list_services as the alternative, so it is clear but not fully 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?

Usage is only implied: an agent can infer this is for inspecting scheduled timers, and 'no params' signals a simple enumeration call. There is no explicit when-to-use/when-not guidance and no mention of the sibling list_services tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false; the description's "Read-only SysKnife action" merely restates that, earning no credit. Beyond the safety profile nothing is disclosed — no return shape, no scoping to the invoking user vs. all users, and no note that an empty toolbox set is a normal result.

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?

Very short and front-loaded, which is good, but the leading sentence "Read-only SysKnife action `ListToolboxes`" spends roughly half the text repeating the tool name and the readOnlyHint already in structured data. The genuinely useful clause is only the trailing fragment.

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 read-only list operation with no output schema and rich annotations, the description covers the essential act and its scope (toolboxes for a given user). Incompleteness is limited to the unresolved username/schema mismatch, which is a parameter issue rather than a missing behavioral concern.

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

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

The input schema declares no properties (0 parameters, additionalProperties: true), yet the description asserts a required "username*" argument. That is the only parameter semantics available, but it directly conflicts with the structured schema, so an agent reading the schema would call with an empty object while the description implies the call will fail without a username.

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 pair ("list toolbox containers for a user"), which is more informative than the name alone and distinguishes it from generic container tools. It does not, however, contrast itself with near-siblings such as sysknife_list_containers, sysknife_distrobox_list or sysknife_multipass_list, so an agent must infer that "toolbox" means the Toolbx/fedora-toolbox subsystem.

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 exclusions and no mention of alternatives. The only routing signal is the word "toolbox", and the neighboring list_containers/distrobox/multipass tools are never referenced, so an agent has no stated rule for choosing among them.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' merely restates structured data. The one genuine addition is the scope word 'local' and 'all', implying no filtering and no directory/LDAP users — modest but real context beyond the annotations.

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

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

Two short clauses, front-loaded with the action name and immediately followed by the plain-language behavior. Only waste is the redundant 'Read-only' qualifier already covered by annotations.

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

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

For a zero-param, read-only enumeration tool with rich annotations, the definition covers what is needed to call it correctly. With no output schema, a brief note on what fields each user entry contains would be the only meaningful addition.

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

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

The tool takes zero parameters, so the baseline is 4. The description's 'no params' correctly confirms this and prevents an agent from hunting for filter arguments.

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

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

States a specific verb and resource: list all local user accounts. It is clearly distinguishable from siblings such as sysknife_list_groups or sysknife_get_sudo_grants by the resource named, though it never explicitly routes the agent away from those neighbors.

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 'list all local user accounts — no params', which tells the agent this is an unfiltered enumeration call. There is no explicit statement of when to prefer it over siblings like sysknife_get_password_aging or sysknife_get_sudo_grants, and no 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?

The description repeats 'read-only' twice and 'no params', all of which the annotations and schema already declare (readOnlyHint=true, idempotentHint=true, destructiveHint=false, zero properties). The only added context is that the listing includes VM state, which hints at return content but is thin.

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 short, front-loaded sentence with no wasted preamble. It loses a point for restating read-only twice, which is redundant with the annotations.

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

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

For a zero-param, read-only listing with full annotation coverage, an agent has everything needed to call it and knows it returns VM names and state. A brief note on return shape would make it complete, but little 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?

The tool takes zero parameters, so the baseline is 4. The description's 'no params' note is consistent with the schema even if redundant.

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

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

States a specific verb and resource: list Multipass VMs and their state. The 'Multipass' resource is unique among siblings (distrobox_list, list_containers, snap_list), so an agent can distinguish it, though it never explicitly contrasts itself 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?

Usage is implied rather than stated: the tool is a read-only listing for Multipass VMs. There is no explicit guidance on when to choose it over other list/state tools or any exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds the concrete source path (/etc/netplan/) and confirms no parameters. However, it does not disclose whether elevated privileges are needed to read those files, nor what form the config comes back in (raw YAML vs parsed), so it adds only modest context beyond the annotations.

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

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

Single dense sentence, front-loaded with the action and the resource. Slightly weakened by repetition ('Read-only SysKnife action' at the start and 'read-only' mid-sentence) and by awkward escaped quoting.

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

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

There is no output schema, so the description carries the burden of saying what comes back, and it never does — the agent cannot tell whether it receives YAML text, a parsed object, or a diff of files. The source path and sibling distinction are present, but the return-shape gap leaves it only adequate.

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

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

Zero parameters, which is the baseline-4 case; the description correctly reinforces 'no params' so the agent knows not to synthesize any.

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 ('read the SAVED network configuration: the netplan YAML in /etc/netplan/') and explicitly contrasts itself with GetNetworkStatus. An agent can tell exactly what this returns versus the live-state sibling 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?

Names the alternative tool and the condition that selects it ('as opposed to GetNetworkStatus which reports live interface state'), plus the domain caveat that on Ubuntu this is what 'the network config' means. Explicit when-to-use-this-vs-that 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?

Description reveals the output structure (typed steps, risk levels, commands, transaction IDs) and the critical workflow constraint (stop and wait for real terminal approval). No annotations are provided, so the description carries the full burden; it does not contradict any.

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 concise sentences: the first describes purpose and output, the next two provide essential usage instructions. No redundant information, well front-loaded.

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

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

Given the output schema exists, the description appropriately summarizes return types. The usage workflow is fully explained, and the single parameter is well-covered. No gaps.

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

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

The single parameter 'intent' has a complete description in the schema (100% coverage). The tool description does not add additional meaning beyond that, 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?

The description clearly states it plans a Linux system administration intent and returns structured steps with risk levels, commands, and transaction IDs. It distinguishes from sibling tools like sysknife_execute and sysknife_audit_verify by focusing on the planning phase.

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 instructs the agent to present the plan, then STOP, and requires the user to run 'sysknife approve' in a terminal. It also warns not to execute from chat approval alone, providing clear usage boundaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the repeated 'read-only' phrasing adds nothing. The one genuine addition is the systemd-resolved host prerequisite, which tells the agent the operation may be inapplicable on some targets. It stops short of describing the failure mode or the shape of what comes back.

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 purpose first, then the concrete command, then scope constraints — no wandering. The only waste is 'Read-only' opening the sentence and 'read-only' closing it, a redundant repetition of information already carried by annotations.

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

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

For a zero-parameter, no-output-schema status read with full annotation coverage, this is close to sufficient: purpose, underlying command, and host requirement are all present. An agent can select and call it confidently; only the behavior on non-systemd-resolved hosts is left unstated.

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

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

Zero parameters, so the baseline is 4. The description's 'no params' is consistent with the empty object schema and confirms the agent need not construct an argument payload.

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 ('show DNS resolution status for all network interfaces') and maps it to the literal command '(resolvectl status)', so the agent knows exactly what it retrieves. It does not explicitly distinguish itself from near-neighbors like sysknife_get_network_status or sysknife_netplan_get_config, but the DNS-resolver framing is specific enough to be recognizable.

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?

'cross-distro (any systemd-resolved host)' gives an implicit applicability condition, which is real guidance. However, it never says when to prefer this over sysknife_get_network_status, nor what happens on a host without systemd-resolved, and no alternatives are named — the caller must infer the boundary.

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

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

Annotations already declare read-only, idempotent and non-destructive behavior, so the description only needs to add context. It contributes the 'no username needed' auth note, but says nothing about whether searches hit remote registries, result limits, or failure 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?

One dense sentence with the action front-loaded and the parameter note trailing. It is efficient, though the dash-separated fragment reads slightly run-on for a tool description.

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

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

For a simple read-only search this is close to sufficient, but there is no output schema and the description never indicates what a result contains or whether remote name filtering is possible. Those gaps are minor but real.

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 declares no properties, so the description's 'param: term* (query string)' is the only documentation of the input and helpfully marks it required. That is real added meaning, though no format examples or matching semantics are given.

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 ('search Flatpak remotes for apps'), which clearly separates it from list_installed_flatpaks and get_flatpak_app_info. It does not explicitly name which sibling to use instead, 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?

'Search Flatpak remotes for apps' implies the lookup use case and 'no username needed' removes an auth question. There is no explicit when-to-use/when-not guidance and no pointer to alternatives such as list_flatpak_remotes or get_flatpak_app_info.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, and the description merely restates 'read-only' twice without adding context. It says nothing about behavior for an unknown or non-existent snap name, which is the main failure mode for an info lookup.

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?

Compact and front-loaded, but 'read-only' appears twice and the internal action identifier `SnapInfo` adds nothing for an agent; roughly a third of the text is redundant.

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

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

For a simple read-only lookup with full annotation coverage, it conveys purpose plus returned fields, which is close to sufficient. The gap is the mismatch between the mentioned required `name` parameter and an empty schema, plus no note on unknown-snap behavior.

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

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

The schema declares no properties at all, so the description's 'param: name*' is the only signal that a snap name must be supplied — genuine added value. It does not explain the expected format of the name or how it is passed, but it is the sole source of this information.

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 ('show snap details') and enumerates the returned fields (version, channel, description), which clearly separates it from sysknife_snap_list. It stops short of naming the sibling explicitly, so differentiation is inferred rather than stated.

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 and no mention of alternatives such as sysknife_snap_list for enumeration or sysknife_search_flatpak_apps for discovery. The agent must infer the use case from the word 'details' 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description's 'read-only' adds no information beyond structured fields. It says nothing about output shape, ordering, or whether it covers only installed snaps versus all known snaps.

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?

Very short and front-loaded with the useful content. It loses a point for restating 'read-only' twice (once at the start, once at the end) — the trailing repetition earns nothing.

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?

A zero-parameter, read-only listing tool whose safety profile is fully covered by annotations; the description is sufficient to call it correctly. Only the missing distinction from the sibling snap_info tool keeps it from a 5.

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

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

There are zero parameters, so the baseline is 4. The description's 'no params' correctly confirms the tool takes no arguments, matching 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?

Names a specific verb and resource — 'list installed snaps' — so the agent knows exactly what it returns. It does not differentiate from the near-identical sibling sysknife_snap_info (single-snap details) in the large sibling set, leaving that inference to the agent.

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?

No when-to-use context, no exclusions, and no routing to alternatives such as sysknife_snap_info or the flatpak listing tools. The only guidance is the implicit 'no params' hint for invocation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, and the description only restates 'read-only' twice. It adds no context about scope (system vs. per-user Flatpaks), permissions needed, or result shape that would go beyond the structured fields.

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?

Very short, but 'Read-only' is stated twice in one sentence and the backticked internal action name `UbuntuListFlatpaks` consumes space without adding meaning for a caller. The bogus `username*` token is noise that must be parsed and discarded.

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 idempotent read with full annotation coverage, the description is close to sufficient, but the invented `username*` parameter and the lack of differentiation from `sysknife_list_installed_flatpaks` leave an agent with open questions before invoking it.

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

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

The schema declares zero properties (additionalProperties: true), yet the description advertises 'param: username*' as if a required username existed. That phantom parameter contradicts the schema and would lead an agent to pass an argument nothing documents, rather than clarifying the (nonexistent) inputs.

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

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

States a specific verb and resource: 'list installed Flatpak apps', which is clearly a read operation. However, it does not distinguish itself from the near-identical sibling `sysknife_list_installed_flatpaks` (nor from `sysknife_get_flatpak_app_info` / `sysknife_search_flatpak_apps`), leaving an agent unable to choose between them from the description 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?

No when-to-use, when-not-to-use, or alternative guidance is given. With a sibling named `list_installed_flatpaks` that appears to do the same thing, the absence of any disambiguation is a real selection hazard rather than a minor omission.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the repeated "read-only" phrasing earns nothing. The genuinely additive content is the behavioral difference between modes: numbered mode emits rule_number values usable by a delete action, while the default keeps verbose status — output-shape context that matters since no output schema exists.

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 a single compact sentence, but it opens with a redundant label ("Read-only SysKnife action `UfwStatus`") and closes with "; read-only", duplicating both the opening and the annotations. The useful scoping and parameter content is buried mid-sentence after the filler prefix.

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 defined properties and no output schema, the description must carry the full burden, and it does cover both output modes and the follow-on workflow. Gaps remain around failure behavior (ufw absent/disabled) and required privileges, which matter for a host-configuration reader.

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 declares zero properties (additionalProperties only), so the description is the sole documentation of the `numbered` flag; it supplies type (boolean), default (false), and the concrete effect of each value. It stops short of clarifying where the flag must be placed in the otherwise empty argument object, which would remove remaining ambiguity.

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: "show current ufw status and rules", which is unambiguous about what the tool returns. It does not differentiate itself from firewall-adjacent siblings such as sysknife_get_firewall_state, sysknife_get_firewall_backend_state, or sysknife_get_nftables_ruleset, so an agent choosing among them gets no routing help.

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

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

The description gives solid conditional guidance for the parameter (numbered=true vs false) and links true to a downstream workflow with UfwDeleteRule. However, it never says when to prefer this tool over the other firewall-state siblings, nor any preconditions (ufw installed/enabled, privilege requirements).

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