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

Goes beyond the annotations by disclosing the underlying mechanism: apt-get install -y via sudo, i.e. non-interactive and requires root privileges. It does not state error behavior or what happens on partial failures, but it adds real operational context.

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

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

A single front-loaded sentence with the action, resource, and execution mechanism, 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?

For a simple one-parameter mutation tool with annotations covering the safety profile and no output schema, the description is largely sufficient. A note on refreshing package lists beforehand would close the remaining gap.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents it. The description adds only the plural/one-or-more semantic, which is marginal value.

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

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

States a specific verb (Install) and resource (apt packages), clearly distinct from apt_remove and apt_upgrade. It does not explicitly call out those siblings, but the action 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?

No guidance on when to use this versus apt_upgrade, nor a prerequisite note that apt_update should typically run first to refresh indexes. Usage is only implied by the tool 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=true and destructiveHint=false, so the safety profile is covered. The description adds the substring-matching behavior of the filter but says nothing about result size, ordering, or pagination for a potentially long package list.

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

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

Two compact sentences with zero filler; the core action is front-loaded and the optional parameter is noted afterward.

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 listing tool with one optional, fully documented parameter and annotations covering safety, nothing essential is missing.

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

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

Schema description coverage is 100%, so the single 'filter' parameter is fully documented in the schema, and the description only restates it as a name substring match. Baseline 3 applies 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 (list) and resource (installed apt packages) plus scope, so it is clearly distinguishable from apt_install/apt_remove. It does not explicitly contrast with the closest sibling, apt_search, which lists non-installed packages.

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 name and the phrase 'installed apt packages'. There is no statement of when to prefer this over apt_search or apt_show, nor any exclusion 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=false and destructiveHint=true, so safety is covered. The description still adds real behavioral value by disclosing that this maps to 'apt-get remove' and that config files survive — the key side effect an agent needs to reason about. It stops short of mentioning dependency handling or required 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?

Two short sentences, zero waste, with the destructive scope and the alternative routing both front-loaded. Nothing could be cut without losing routing 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 one-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies everything needed: what it removes, what it preserves, and where to go for the purge variant. No material gap remains.

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

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

Schema coverage is 100% and the single 'packages' array parameter is already documented. The description only echoes plurality ('one or more'), adding no format, naming, or wildcard guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Remove one or more apt packages') and immediately qualifies the scope, distinguishing it from purge by noting config files are left behind. An agent can tell it apart from apt_install and the sudo/purge path 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 routes the purge case to an alternative ('Use run_command_sudo for purge'), naming both the sibling tool and the condition that selects it. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 and destructiveHint=false, so the safety profile is covered. The description adds that matching is against name or description, but says nothing about result volume, ranking, or whether it queries a local cache versus remote indices.

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 zero filler; the verb and resource come first and every word earns its place.

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

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

For a trivial one-parameter read-only search with full schema coverage and no output schema, the description is nearly sufficient. It lacks only a note on scope (local apt cache vs repositories) and result behavior, which are minor for this complexity level.

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 documents the single query parameter at 100% coverage, so the baseline is 3. The description's 'by name or description' clarifies what the query matches against, adding mild value beyond the schema's bare 'Search term'.

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 (search) and resource (apt packages) plus the matching fields (name or description), which separates it from apt_list_installed and apt_show. It does not explicitly name a sibling, so it falls just short of a 5.

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

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

Usage is implied by the verb: search when you don't know the exact package name, versus apt_show for a known package or apt_list_installed for what's already on the system. However, no when-to-use or when-not-to-use guidance is stated, so the agent must infer it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'apt-cache show' detail, implying a local cache read rather than a network fetch, but says nothing about failure behavior for unknown packages or output volume. Modest added value above 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?

A single front-loaded sentence with the verb, resource, and the equivalent CLI command. Nothing 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?

For a simple one-parameter read-only tool with full schema coverage and annotations covering safety, the description is nearly sufficient. Only the distinction from apt_search/apt_list_installed is left implicit, which is a minor gap.

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

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

Schema description coverage is 100% and the single 'package' parameter is documented in the schema as 'Package name'. The description adds no format details (e.g. whether versioned specs like pkg=1.2 are accepted), so the baseline 3 applies.

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

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

States a specific verb and resource ('show detailed information about a package') and pins the exact underlying operation (apt-cache show), which separates it from apt_search and apt_list_installed. It does not explicitly name those siblings, but the 'detailed information' scope is distinct enough for an agent to differentiate.

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 guidance, no mention of alternatives such as apt_search (find a package) or apt_list_installed (list installed packages). The agent must infer the routing 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=false and destructiveHint=false, so the safety profile is covered. The description adds that the operation requires sudo, which is genuine behavioral context beyond the structured fields, but it omits anything about effects on the system beyond the index refresh.

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

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

A single tight sentence with the action front-loaded and a parenthetical noting the privilege requirement. No waste, though extremely terse – more differentiation from siblings could fit without bloat.

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 maintenance tool this is adequate, and the sudo hint is useful. It stops short of stating the typical workflow (refresh before installing/upgrading) or when it should not be run, leaving gaps an agent would want filled.

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 implies no arguments are needed and adds nothing that would mislead about 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+resource ('refresh package index') and identifies the underlying command (apt-get update), which distinguishes it from siblings like apt_upgrade or apt_install. Clear, though not explicitly contrasted with those siblings.

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

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

No when-to-use guidance or relationship to alternatives. It never states that this should be run before apt_install/apt_upgrade, nor when to skip it. An agent must infer its role from the 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 it is not read-only and not destructive; the description adds that installed packages are modified system-wide and that dry_run gives a safe preview, which is useful context. It omits prerequisites (refreshed package lists), privilege requirements, and whether upgrades are reversible, so it adds only moderate value 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?

Two short sentences, front-loaded with the action and followed by the safety lever. 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?

For a one-parameter tool with no output schema this is roughly adequate, but a package upgrade is a system-mutating operation and the description leaves out prerequisites (an apt_update first) and privilege needs that an agent would want 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?

Schema coverage is 100% and the single parameter already carries the description 'Preview changes without applying'. The description restates the same meaning for dry_run without adding format or side-effect detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Upgrade installed packages') and anchors it to the underlying operation ('apt-get upgrade'), which lets an agent distinguish it from apt_update and apt_install. No explicit sibling differentiation is written out, but the parenthetical command is enough to place it.

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 only guidance is 'Set dry_run=true to preview without applying', which is a usage hint for the single parameter rather than a when-to-use statement. It never says whether apt_update should be run first or when to prefer this over apt_install for new packages, so usage is only implied.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered structurally. The description adds the useful constraint that non-empty directories require recursive=true, but says nothing about irreversibility, permission failures, or error behavior 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?

Two short sentences, front-loaded with the core action and immediately followed by the one non-obvious parameter condition. 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 simple two-parameter delete whose safety profile is fully carried by annotations and with no output schema to explain, the description is nearly sufficient. It could mention irreversibility or error cases, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description's mention of recursive=true for non-empty directories adds a little practical meaning beyond the schema's 'Delete recursively (for directories)', but it is essentially a restatement, so the baseline 3 applies.

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

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

States a specific verb ('Delete') and resource ('file or directory'), which cleanly separates it from the many read/write siblings such as read_file, write_file, and list_directory. An agent can identify the operation without opening the schema.

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

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

The description gives one conditional hint (recursive=true for non-empty directories), which is really about parameter usage rather than when to choose this tool over alternatives. It never states when not to use it or names a sibling as an alternative, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful content about what is returned (load averages, core count, top snapshot), but does not state that the snapshot is a point-in-time reading or whether values are averaged over intervals, which matters for interpreting 'load averages'.

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

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

A single front-loaded sentence with no filler; the resource and return payload are stated immediately and 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, parameterless, non-destructive read with no output schema, listing the three returned data groups is enough for an agent to call it correctly. Only the absence of any hint about the overlap with get_top_processes keeps it from being fully 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. Schema coverage is moot here since the properties object is empty.

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 ('Returns') and resource ('CPU') and enumerates the returned fields (load averages, core count, top snapshot). It is clearly distinguishable from get_memory_usage and get_disk_usage by resource, though it never explicitly contrasts itself with sibling get_top_processes, which overlaps with the 'top snapshot' phrase.

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 the many sibling diagnostics (get_system_info, get_top_processes, list_processes). The description gives no context, prerequisites, or exclusions, leaving the agent to infer usage from the 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 and destructiveHint=false, so the safety profile is covered. The description adds the concrete data sources (df -h and lsblk), which is useful behavioral context about what will be returned, but it does not discuss output structure, host-side variability, or permissions.

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 zero filler; every clause (df -h, lsblk) carries information.

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

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

For a zero-parameter, read-only tool with no output schema, the description is sufficient: it names the data returned and the commands used. An agent has everything needed to select and call 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 tool takes no parameters, so there are no parameter semantics to misrepresent; baseline 4 applies. The description correctly implies a parameterless invocation.

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 ('Returns') and resource (disk usage per mount point plus block device layout), naming the exact underlying commands (df -h, lsblk). This clearly differentiates it from siblings like get_cpu_usage, get_memory_usage, and get_system_info without needing to open 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?

There is no explicit guidance on when to use this tool, when not to, or which sibling to prefer (e.g., get_system_info may partially overlap). Usage is only implied by the tool's obvious subject matter.

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 and destructiveHint=false, so the safety profile is covered by structured data. The description adds the useful 'stat'-style behavioral framing, but says nothing about what happens on a nonexistent path, symlink resolution, or permission-denied cases.

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 tightly written sentence, front-loaded with the action and immediately followed by the concrete fields returned. No filler, though it is arguably terse enough to leave the reader wanting a bit more.

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

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

For a single-parameter, read-only metadata tool with no output schema, the description covers what is returned and against what input. The remaining omissions (error cases, symlink behavior) are minor for a simple stat-like operation.

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

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

Schema description coverage is 100% and the single 'path' parameter is fully documented as an absolute path to file or directory. The description adds no syntax or format detail beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

States a specific verb (Get) and resource (file metadata) and enumerates the returned fields — permissions, owner, size, timestamps — which distinguishes it from content-oriented siblings like read_file and tail_file. It stops short of explicitly naming those siblings, so an agent must infer the metadata-vs-content 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?

There is no when-to-use guidance, no mention of alternatives (read_file, list_directory, get_system_info), and no stated prerequisites or error behavior. Usage is only implied by the word 'metadata'.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful filter semantics (priority scale, relative time formats), but omits permission requirements, default line behavior, and truncation effects that would matter for a journal reader.

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 core action and then lists filters in schema order. Slightly dense with colon-delimited clauses, 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?

All five parameters are documented in the schema and filters are explained, but with no output schema the description should ideally say what the returned log entries look like. Combined with the missing sibling routing and permission caveats, it is adequate but not complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does marginally enrich the priority parameter by enumerating the full 0-7 / emerg-to-debug scale, which the schema only abbreviates as 'err, warning, info, debug, etc.' That said, it adds no new meaning for unit, lines, since, or until.

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 (Fetch) and resource (systemd journal logs) with scope qualification (optional filters). However, it never distinguishes itself from close siblings like search_logs and tail_file, leaving the agent to infer which log-retrieval tool applies.

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 over search_logs or tail_file, and no mention of prerequisites such as needing elevated privileges to read journal data. The agent must guess based on tool names 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 and destructiveHint=false, so the safety profile is covered. The description adds useful provenance ('free -h and /proc/meminfo'), telling the agent roughly how values are sourced/rounded, but says nothing about freshness, sampling, or units beyond that hint.

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

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

A single front-loaded sentence with no filler; the resource comes first and the data sources are parenthesized. It is efficient, though arguably borderline terse for a tool with no output schema.

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

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

With no output schema, the description carries the burden of describing the return value. It names the returned data (RAM and swap usage) but not the structure, units, or whether a single snapshot is returned, leaving the shape of the response partly undefined.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to get wrong or clarify. The description introduces no misleading parameter 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 ('Returns RAM and swap usage'), which cleanly separates it from siblings like get_cpu_usage, get_disk_usage, and get_system_info. It does not explicitly name those siblings or state the boundary with get_system_info, 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: an agent can infer it should call this when memory/RAM/swap metrics are needed. There is no explicit when-to-use statement or guidance about preferring get_system_info for aggregate host info versus this for memory detail.

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 without description help. The description adds the return content ('IPs and link status') and the underlying commands (ip addr, ip link), which is modest but real added context.

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

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

A single front-loaded sentence with no filler, stating what is returned and how it maps to standard Linux tooling. Every clause earns its place.

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

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

With no parameters, no output schema, and full annotation coverage, the description supplies enough for correct invocation and even hints at the returned fields. Only a brief note on output format detail would make it fully 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and the empty schema is consistent with the described behavior.

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 ('Returns') and resource ('all network interfaces') plus the scope of returned data (IPs and link status). This clearly separates it from the surrounding system-info siblings like get_system_info, get_cpu_usage, and get_disk_usage.

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 no explicit when-to-use statement or named alternatives, but the narrow resource scope makes selection among siblings largely self-evident for a zero-parameter tool. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description contributes the fact that lookup can be by PID or by name, but says nothing about behavior when neither parameter is supplied, when both are supplied, or what happens on no match.

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 sentence with the resource and lookup modes front-loaded and no filler. Nothing to trim.

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 give some sense of what 'details' are returned, and it does not. For a simple two-optional-parameter read tool this is minimally viable, but an agent cannot predict the payload shape.

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

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

Schema description coverage is 100% and both parameters are documented in the schema (PID, substring match on name). The description restates the same two lookup keys without adding format, precedence, or conflict-handling semantics. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Get details about a specific process') and identifies the lookup modes (PID or name). It is clearly distinguishable from list_processes, get_top_processes, and kill_process, though it 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?

There is no when-to-use guidance, no mention of alternatives such as list_processes or get_top_processes, and no exclusions. The intended usage is only inferable from the tool name and verb.

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 elsewhere. The description's added value is the list of returned fields, which is meaningful given there is no output schema, but it says nothing about permissions, cost, caching, or response format.

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 front-loaded sentence with zero filler; every listed field earns its place by defining the payload in the absence of an output schema.

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

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

For a zero-parameter, read-only tool whose safety is covered by annotations, the enumeration of returned fields compensates well for the missing output schema. Only minor gaps remain around response format and the fact that it is argument-free.

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 schema is empty, so there is no parameter surface to document. Baseline 4 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?

Specific verb ('Returns') plus a concrete enumeration of the resource contents (hostname, OS version, kernel, uptime, architecture), which cleanly separates it from the metric-focused siblings get_cpu_usage, get_memory_usage and get_disk_usage. It never names a sibling explicitly, 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?

Usage is only implied: an agent can infer this is the general host-facts call versus the per-metric siblings, but the description never states when to prefer it or that it takes no arguments. No exclusions or prerequisites are given.

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 and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds essentially no behavioral context beyond that — it doesn't explain how CPU/memory usage is sampled, whether results are a snapshot, or what the returned fields look 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?

A single tight sentence with no filler, and the ordering criterion is front-loaded. Nothing is wasted, though there is also very little substance.

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 tool with defaulted parameters, no output schema, and annotations covering safety, the description is minimally adequate. It still leaves the sampling semantics of 'CPU or memory usage' undefined, which matters for interpreting the ranking.

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

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

Schema description coverage is 100%, so both parameters (count, sort_by) are documented in the schema with defaults, bounds, and an enum. The description echoes the general shape ('top N', 'CPU or memory') but omits the 'pid' sort option, so it adds nothing beyond the schema baseline.

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

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

States a specific verb and resource ('Get top N processes') plus the ordering criterion, which separates it from the plain list_processes sibling. It does not, however, explicitly contrast itself with list_processes or get_process, leaving the agent to infer the distinction.

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 guidance is given: nothing says when to prefer this over list_processes or get_process, nor whether the counts are instantaneous or averaged over an interval. The agent must guess the intended context.

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 flag destructiveHint=true/readOnlyHint=false, so the bar is lower, yet the description adds real context: SIGTERM is graceful by default, SIGKILL forces termination, and the operation runs via sudo (elevated privileges). These are meaningful operational facts 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?

Four short sentences, front-loaded with the core action and default behavior, then the escalation path and the privilege note. No filler.

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

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

For a two-parameter destructive tool with no output schema, the description plus annotations cover the essentials: what it does, the default and forced signals, and that it runs with sudo. It stops short of warning about irreversibility or describing the return, but it is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning not present in the schema by characterizing SIGTERM as graceful and SIGKILL as forcing termination, helping the agent choose a signal value rather than just a type.

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: sending a signal to a process identified by PID. This is clearly distinguishable from the read-only process siblings (list_processes, get_process, get_top_processes), though it never names them 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?

It implies when to use SIGTERM vs SIGKILL, but that is signal selection rather than tool selection. There is no explicit guidance on when to reach for kill_process over the adjacent process-inspection 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=true and destructiveHint=false, so safety is covered. The 'ls -la' analogy adds real context (detailed/long format, hidden files included), but nothing is said about recursion, output format, ordering, or pagination for large directories.

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 sentence with the resource front-loaded and the format hint appended; 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 simple read-only tool with annotations and a fully documented single parameter, the essentials are present. But with no output schema, the description does not convey what the listing returns (names only vs. permissions/sizes, sorting, hidden-file behavior beyond the 'ls -la' hint), leaving a gap for the caller.

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

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

Schema description coverage is 100% and the single 'path' parameter is documented as an absolute path, so the baseline of 3 applies. The description adds no constraint or format detail beyond what the schema already states.

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

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

States a specific verb and resource ('List directory contents') and clarifies the shape of the result via the 'ls -la' analogy, which signals long-format detailed output including hidden entries. However, it does nothing to distinguish this from siblings like read_file, get_file_info, or tail_file.

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 over read_file, get_file_info, or search-related tools, and no stated prerequisites or exclusions. The agent must infer usage entirely 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 establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it reveals the underlying command (ps aux) and, importantly, that results are truncated to the top 60, which the agent needs in order to interpret a short result list correctly.

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

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

One sentence, zero waste, front-loaded with the action and resource, followed by the sort options and the result cap. Nothing is padded.

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

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

There is no output schema, so the description must carry return-value information, and it does with 'Returns top 60'. The main remaining gap is the absence of guidance relative to get_top_processes/get_process for a tool that clearly overlaps with them.

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

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

Schema description coverage is 100% and the single parameter has an enum plus default, so the schema fully documents it. The description restates the same sort options and adds nothing beyond the schema – baseline 3.

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

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

States a specific verb+resource ('List running processes') and even names the underlying mechanism ('ps aux'), so the agent knows exactly what is produced. It does not differentiate itself from adjacent siblings like get_top_processes or get_process, which is the only thing keeping it out of 5 territory.

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 or when-not-to-use statement, and no alternative is named. The overlapping sibling get_top_processes makes that omission material – an agent has no stated rule for choosing between 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?

Annotations declare readOnlyHint=false and destructiveHint=false, establishing this as a non-destructive write. The description adds genuinely useful behavioral context beyond that: 'mkdir -p' semantics mean parent directories are created as needed and an existing directory is not an error, which an agent needs to know. It does not cover failure/permission behavior, keeping it from 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?

A single, tightly-worded sentence with the core action front-loaded and the informative mkdir -p clarification parenthesized. Every clause earns its place with no 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 one-parameter, no-output-schema tool this is nearly complete: it explains the action and the parent-directory creation behavior. It leaves error handling and permission requirements unstated, but those are minor for this operation.

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

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

Schema coverage is 100%, so the single 'path' parameter is fully documented in the schema itself. The description adds no syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb ('Create') and resource ('directory'), and the mkdir -p note clarifies the scope of what gets created. It does not explicitly name or contrast with siblings like list_directory or delete_file, but the purpose is unambiguous.

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

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

There is no guidance on when to use this versus alternatives (e.g., run_command with mkdir, or write_file). Usage is only implied by the plain meaning of 'create a directory'. No prerequisites or conditions are 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=true and destructiveHint=false, so the safety profile is covered. The description adds one useful constraint (1MB output limit), but says nothing about encoding, binary files, truncation behavior, or error cases such as missing paths.

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

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

Two short sentences with the purpose front-loaded and the constraint immediately after. 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 no output schema, the description should carry more of the return-value burden; it notes the 1MB limit but not what happens on truncation or how content is returned. Adequate but with clear gaps for a file-reading tool in a large filesystem-oriented toolset.

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

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

Schema description coverage is 100% and the single 'path' parameter is documented as an absolute path in the schema. The description adds no further meaning, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (contents of a file), which distinguishes it from write_file and delete_file. It does not, however, differentiate itself from near-siblings like tail_file or get_file_info, leaving the agent to infer boundary cases.

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 choose this over tail_file (last N lines), get_file_info (metadata), or list_directory. The agent must infer usage conditions from the 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=false, openWorldHint=true and destructiveHint=false. The description adds operationally important limits the annotations do not carry: a 30s timeout and a 1MB output cap, which materially affect how an agent designs a command.

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

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

Three short clauses, front-loaded with the action, then constraints, then routing advice. No sentence is filler and nothing needed for selection is buried.

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

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

For a one-param arbitrary-shell tool with annotations covering the safety profile and no output schema, the description supplies the timeout, output cap, and intended scope. The only meaningful omission is any privilege/auth distinction relative to run_command_sudo.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents it fully; the baseline for that case is 3. The description adds no syntax, quoting, or shell-resolution guidance beyond the schema's 'Shell command to execute'.

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 ('Execute an arbitrary shell command') and names the return payload (stdout/stderr), which is more than a restatement of the name. It does not, however, distinguish itself from the sibling run_command_sudo, which an agent would need to route between.

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 operations not covered by structured tools' gives a clear fallback condition that selects this tool over the many structured siblings. It stops short of an explicit when-not (e.g. preferring apt_install over shell apt) or any mention of the sudo variant.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, so the danger profile is covered. The description adds the privileged-escalation detail, but 'Same limits as run_command' references constraints without stating them, leaving the actual limits undefined. Adequate but with a real gap the description could have closed.

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

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

Three short sentences, front-loaded with the action, then scope, then routing guidance. No filler or repetition; every sentence carries distinct 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 single-parameter tool with an output-less design and annotations covering the safety profile, the description supplies enough to invoke it correctly. The only shortfall is the unexplained 'same limits as run_command', which leaves a behavioral constraint undefined.

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

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

Schema description coverage is 100% and there is exactly one parameter, already documented as 'Shell command to execute with sudo'. The description only restates 'arbitrary shell command' and adds no syntax, escaping, or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource (execute arbitrary shell command) and qualifies it with 'with sudo', clearly separating it from run_command (unprivileged) and the structured apt/service/zfs tools. An agent can tell what it does and how it differs from siblings without opening the schema.

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

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

Explicitly says to 'use for privileged operations not covered by structured tools' and gives concrete examples (apt purge, iptables), which routes the agent away from the structured siblings. It stops short of stating when NOT to use it or naming the fallback for non-privileged commands explicitly, so it is not a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it is case-insensitive (grep -i) and result-capped at the last 200 matching lines, which tells the agent output may be truncated. It stops short of explaining ordering or what happens when the cap is hit.

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

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

Three tight sentences with no filler; the core action comes first, then the optional filter, then the return behavior. Every clause earns its place.

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

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

With no output schema, the description usefully states the return shape ('last 200 matching lines'), which is the key fact an agent needs for a search tool. It is nearly complete, missing only finer detail on result ordering and truncation behavior.

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

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

Schema description coverage is 100%, so both 'unit' and 'pattern' are already documented in the schema. The description's 'grep -i' phrasing reinforces the case-insensitive semantics but adds no syntax, edge-case, or formatting detail beyond the schema text. Baseline 3 applies 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 ('Search journal logs for a pattern') and adds the grep -i comparison, so an agent knows it is a filtered text search rather than a full dump. It does not explicitly contrast itself with the nearby get_journal_logs or tail_file siblings, leaving that distinction to inference.

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

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

The 'optional unit filter' hints at the scoping use case, but there is no explicit statement of when to reach for this tool versus get_journal_logs (bulk retrieval) or tail_file. Usage is implied rather than guided, and no exclusions or alternatives 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 destructiveHint=true and readOnlyHint=false, so the write nature is covered. The description adds useful context beyond that: it requires sudo and applies to system scope only, telling the agent about the privilege requirement and the persistence (boot-time behavior) of the change.

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, front-loaded sentences with no filler; the core action and its boot-time scope lead, and the privilege/scope caveats follow.

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

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

For a one-parameter tool with no output schema and annotations covering the safety profile, the description supplies the privilege and scope constraints an agent needs. It does not state that the currently running service is unaffected, a minor omission.

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

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

Schema coverage is 100% with the single 'name' parameter self-documented as the service name. The description adds no format or naming guidance beyond the schema, so the baseline of 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 gives a specific verb ('Disable') and resource ('a system service'), and clarifies the scope of the action by tying it to 'starting at boot' rather than stopping the service now. That distinguishes it from the service_stop sibling, though it never names the alternative explicitly.

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

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

'System scope only' implicitly signals that user-level services are out of scope, and the '(sudo)' note implies elevated privileges are required. However, it never states when to prefer this over service_stop or service_enable, leaving the use case 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 only declare the operation is non-read-only and non-destructive. The description adds genuinely useful behavioral context beyond that: it requires elevated privileges ('sudo') and the effect is persistent across reboots rather than immediate-only. Does not mention idempotency or error behavior on an already-enabled service.

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 terse clauses, front-loaded with the action and its persistence semantics, then the privilege/scope constraint. 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 one-parameter mutation tool with annotations covering the safety profile and no output schema, the description supplies the essential missing pieces (sudo requirement, boot-persistence, system scope). It is complete enough to call correctly, though not rich.

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?

Single parameter 'name' is fully documented in the schema (100% coverage), and the description adds nothing about naming format, units, or resolution. Per the high-coverage baseline, 3 is the correct ceiling.

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 (enable a system service) plus the key scope qualifier 'to start at boot', which cleanly separates it from service_start (start now) and service_disable (the inverse). An agent can identify this tool 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?

'System scope only' is an explicit exclusion that tells the agent when this tool does not apply (user-scope services), and the sibling set makes the start/stop/enable/disable split obvious. No alternative tool is named for the user-scope case, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no pagination, no ordering, no volume of results or output shape. It essentially restates the schema fields rather than disclosing 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?

Three terse fragments, front-loaded with the core action and free of filler. It is appropriately sized for a two-parameter read tool, though the parameter recap duplicates schema content rather than adding 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 read-only list tool with full schema coverage and non-destructive annotations, the essentials are present. It does not mention result ordering or whether the output can be large, which would help an agent, leaving it adequate but not complete.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the enum and default for scope. The description repeats scope/default and gives an example state value, adding only marginal meaning over the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: "List systemd services." This clearly separates it from mutation siblings like service_start/service_stop/service_restart and from service_status, which is singular. It stops short of explicitly naming those siblings, but the plural list action 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?

Usage is implied by the verb rather than stated. There is no explicit guidance on when to use this versus service_status or get_system_info, nor any exclusions. The scope/state hints give context but not when-to-use routing.

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

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

Annotations already declare this is a non-read-only, non-destructive operation, so the safety profile is covered. The description usefully adds the sudo auth requirement and the system-scope constraint, but says nothing about disruption, downtime, or failure behavior for an already-stopped or nonexistent service.

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, front-loaded sentences with zero filler; the core action precedes the privilege and scope qualifiers. It is terse but every clause carries information.

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

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

For a one-parameter tool with full schema coverage, declared annotations, and no output schema, the description covers purpose, privilege requirement, and scope. Only edge-case behavior (nonexistent service, already-running state) is unaddressed, which is a minor gap.

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

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

Schema description coverage is 100% with a single documented 'name' parameter, so the schema carries the meaning. The description adds no syntax, format, or naming-convention detail beyond the schema's baseline.

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

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

States a specific verb and resource ('Restart a system service'), and the name/title distinguish it from the sibling service_start/service_stop. However, the description does not explicitly differentiate itself from running service_stop followed by service_start, so differentiation is only implicit via naming.

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?

'System scope only' implies a usage boundary, and '(sudo)' signals the required privilege level, but the description never states when to restart versus stop/start or what prerequisites exist. Usage context is implied rather than stated.

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

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

Annotations only declare that this is a non-read-only, non-destructive operation. The description adds the key omitted fact that it requires sudo (elevated privileges) and is restricted to system scope, neither of which appears in the structured fields. It still omits behavior when the service is already running or missing, but it meaningfully exceeds the annotation baseline.

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 terse sentences, front-loaded with the action and followed by the two constraints (sudo and scope). No filler, and every clause carries operational 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 one-parameter mutation tool with no output schema this is close to sufficient: the agent knows the action, the privilege requirement, and the scope. What is missing is idempotency and failure behavior (e.g., service already running, nonexistent service, blocking vs non-blocking), which matters for a state-changing operation whose annotations cover only safety hints.

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

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

Schema coverage is 100% and the single parameter is already described as 'Service name', so the description adds no syntax, format, or naming-convention details. With one fully documented parameter, the baseline of 3 for schema-covered params is appropriate.

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

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

States a specific verb (Start) and resource (system service), and narrows scope with 'System scope only', which distinguishes it from a user-scoped start. It does not explicitly differentiate from siblings like service_restart or service_enable, so the routing signal is clear but not complete.

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

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

Usage is implied by the verb — start a currently stopped service — and the 'system scope only' constraint rules out user services. However, there is no guidance on when to prefer this over service_enable (boot persistence) or service_restart, leaving the agent to infer the distinction from sibling names.

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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is already covered. The description adds the underlying command 'systemctl status' and that it targets a named service, but omits return format, permission needs, and error behavior; with annotations, this is adequate.

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 front-loaded sentence with no filler; every word contributes.

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 status tool with annotations and full schema, the description supplies enough to call correctly. It could mention the scope parameter or output characteristics, but systemctl status is self-explanatory.

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

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

Schema description coverage is 100%, so both name and scope are fully documented in the schema. The description only references 'named service' and adds no semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb 'Get' and resource 'systemctl status for a named service', making the operation clear. It does not explicitly distinguish from sibling service_list or service_start, but the named-service scope is implicit.

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 guidance or alternatives provided. The description says what it does but not when to choose it over service_list or get_system_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 destructiveHint=true and readOnlyHint=false, so the description's real contribution is the '(sudo)' note, which discloses that elevated privileges are required - information not present in the annotations or schema. It does not, however, say anything about dependent services or reversibility.

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

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

Two terse, front-loaded sentences with zero filler; the verb and resource come first and the scoping caveat follows.

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

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

For a one-parameter mutation tool with complete schema coverage, a safety-related annotation, and no output schema, the description supplies the essential privilege context an agent needs. Only minor gaps remain around behavior when the service is already stopped or has dependents.

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 'name' is fully documented in the schema ('Service name'), so the baseline is 3. The description's 'System scope only' adds a mild constraint on which names are valid, but no format or examples are provided.

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 (Stop) and resource (system service), and the '(sudo)' plus 'System scope only' qualifiers add precision about what is being stopped. It is clearly distinguishable from service_start/service_restart/service_disable, though it does not name a sibling explicitly.

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

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

Usage is implied by the name and the scope note, but there is no statement of when to prefer this over service_disable or service_restart, nor any prerequisite or failure-condition guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered structurally. The description usefully adds the previously unknown constraint that the path must fall under an allowed prefix (default /var/log), which an agent needs to avoid a failed call, but it says nothing about error behavior, truncation, or how the tail is computed.

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 no filler, and the purpose is front-loaded before the constraint. It is efficient, though the extreme brevity leaves the usage gap noted above rather than using the space to close it.

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

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

For a simple two-parameter read tool with full annotation coverage and schema descriptions, the description covers the essentials plus the non-obvious prefix restriction. It is minimally adequate: an agent can call it, but the absence of any return-shape or failure-mode note (no output schema exists to compensate) leaves a small gap.

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

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

Schema description coverage is 100%, so both 'path' and 'lines' are already documented, which sets the baseline at 3. The description adds one piece of meaning beyond the schema – that 'path' is validated against an allowed prefix with a default of /var/log – but adds nothing for 'lines' beyond the schema's default and max.

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 verb+resource pair ('Tail a log file') is specific and immediately actionable, and 'tail' semantics distinguish it from a generic read. However, it does not differentiate itself from close siblings like read_file, search_logs, or get_journal_logs, which an agent must choose between for log-reading tasks.

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 states a hard constraint (allowed path prefix) but gives no when-to-use guidance, no prerequisites, and no routing to alternatives such as search_logs or read_file. The agent is left to infer when tailing a single file is the right call versus filtering logs.

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=false and destructiveHint=true, so the safety profile is covered. The description nonetheless adds genuinely useful behavior beyond that: overwrite semantics (existing content is destroyed), a text-only limitation excluding binary files, and a permission requirement. It does not address atomicity, encoding, or parent-directory creation.

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 clauses with zero filler. The most important information — what is written and that it can overwrite — is front-loaded, and the constraints follow in order of relevance.

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

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

For a two-parameter destructive write with no output schema, the description covers the key risks an agent must know: overwrite behavior, text-only scope, and permission requirements. It stops short of stating whether missing parent directories are created, which is a common source of failed invocations.

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

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

Schema description coverage is 100% (both 'path' and 'content' are documented, including that path is absolute and content is the file body). The description adds no per-parameter meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States a precise verb and resource ('Write text content to a file') and immediately clarifies both modes of operation (creates or overwrites). Within a sibling set that includes read_file, delete_file, and make_directory, the write semantics are unambiguous without naming an 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 implied by the verb and the create/overwrite note, but there is no explicit guidance on when to prefer this tool over alternatives (e.g. shell redirection via run_command) and no prerequisites such as whether the parent directory must already exist. The 'requires appropriate filesystem permissions' clause hints at preconditions without specifying 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description's '(sudo)' adds genuinely new context about required privileges, but says nothing about storage consumption, failure behavior on duplicate names, or what happens on an existing snapshot.

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 and immediately followed by the format constraint. No filler; every phrase carries information.

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

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

For a one-parameter tool with no output schema and annotations covering the safety profile, the description is nearly sufficient. It still omits whether the target dataset must pre-exist and how failures are reported, which an agent would want 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?

Schema description coverage is 100% for the single 'snapshot' parameter, and the schema already documents the dataset@snapname format. The description restates the same format rather than adding syntax, validation, or naming rules, so the baseline of 3 is appropriate.

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

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

States a precise verb and resource ('Create a ZFS snapshot'), which naturally separates it from zfs_list_snapshots and zfs_destroy_snapshot. It does not, however, explicitly name or contrast with those siblings, so it falls just short of the top band.

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

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

The only usage signal is the parenthetical '(sudo)', which implies a privilege requirement but never states when to use this tool versus alternatives. No prerequisites (parent dataset must exist) or exclusion conditions are given.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so most of the safety profile is structured data. The description's only real addition is the '(sudo)' note, which tells the agent elevated privileges are required, plus the word 'Permanently' reinforcing irreversibility. Useful but 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 sentence with the destructive/privilege qualifiers front-loaded inline. Zero waste and nothing buried.

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

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

For a single-parameter destructive tool with full schema coverage and safety annotations, the essentials — permanent deletion, sudo requirement — are all present. Missing notes on failure cases (clones, nonexistent snapshots) are the only gap.

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

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

Schema description coverage is 100% ('Snapshot name in dataset@snapname format'), so the single parameter is fully documented in the schema. The description adds no format or validation detail beyond it, which makes 3 the correct baseline.

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

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

States a specific verb+resource ('Permanently delete a ZFS snapshot'), which is precise enough to distinguish it from the sibling zfs_create_snapshot and zfs_list_snapshots. It stops short of explicitly naming an alternative the way a 5 would.

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 guidance, no prerequisites (e.g., must list snapshots first to get the exact dataset@snapname), no mention that snapshots with dependent clones cannot be destroyed. The agent is left to infer the workflow from the 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, and destructiveHint=false, so the safety profile is fully covered. The description adds no further behavioral context such as output format, error conditions for nonexistent datasets, or property-name validation.

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 zero filler, and the primary purpose is front-loaded before the 'all' usage hint. Every clause earns its place.

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

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

For a simple two-parameter read with complete schema coverage and annotations carrying the safety profile, the description is nearly sufficient. A brief note on distinguishing it from the pool-scoped sibling would close the only meaningful gap.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the 'all' sentinel value. The description restates the 'all' behavior without adding syntax or format detail beyond what the schema provides, making 3 the correct baseline.

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

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

Names a specific verb (Get) and resource (properties) with clear scope (ZFS dataset or pool). An agent can distinguish it from zfs_set_property by the read verb, though it doesn't explicitly address the overlap with the sibling zfs_pool_get_property.

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 sentence 'Use "all" for all properties' gives one concrete usage hint, but there is no guidance on when to prefer this tool over zfs_pool_get_property or when a single property is preferable to 'all'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds the set of fields returned, which is valuable given there is no output schema, but says nothing about ordering, scope across pools, or volume of results.

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 zero filler, front-loading the action and returned fields before the optional filter. Every clause earns its place.

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

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

For a simple read-only list tool, the description plus annotations plus a fully documented single parameter is nearly sufficient, and calling out output fields compensates for the absent output schema. Minor gaps remain on result scope and ordering, but nothing blocking 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?

With a single parameter and 100% schema description coverage, the schema already documents 'pool' fully ('omit for all'). The description's 'Optionally filter by pool' restates the schema without adding format or matching semantics, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('List ZFS datasets') and enumerates the returned fields (used, available, compression, recordsize, mount info), which separates it from zfs_list_pools and zfs_list_snapshots by resource. It does not explicitly name those alternatives, 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?

'Optionally filter by pool' implies the usage context but does not state when to use this versus zfs_list_pools or zfs_pool_status. No exclusions or prerequisites are given, so guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description contributes the interesting behavioral detail that results include health and autotrim status, but says nothing about ordering, cost, or how pools are enumerated.

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

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

A single front-loaded sentence that names the verb and resource first, then the salient returned fields. No filler, no redundancy with the title.

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

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

There is no output schema and no parameters, so the description's enumeration of returned fields is doing real work in place of structured output documentation. Combined with annotations that cover the read-only safety profile, this is close to complete, lacking only any note on ordering or scope limits.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No parameter-level value could be added beyond 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 clear verb ('List') and resource ('all ZFS pools') and enumerates the fields returned (size, allocation, fragmentation, health, autotrim), which distinguishes it from single-pool siblings like zfs_pool_status. It does not explicitly name an alternative, so the differentiation is implied 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?

The word 'all' implies a broad overview use case, but there is no explicit when-to-use guidance, no mention of when to prefer zfs_pool_status or zfs_pool_iostat, and no prerequisites or exclusions. Usage must be inferred from context.

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 safety is covered. The description adds what is returned (size, creation time) and the sort order, which is useful context but not deep behavioral disclosure.

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

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

A single tight sentence with the resource and ordering front-loaded. No filler or redundancy.

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

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

For a simple read-only list tool with full annotation coverage and a fully described schema, the description covers the essentials, including the returned fields and sort order absent from an output schema. Only a note about the dataset filter or result scope is missing.

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

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

Schema description coverage is 100% and the single 'dataset' parameter is already documented as a filter with 'omit for all'. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

Specific verb+resource ('List ZFS snapshots') with additional scope detail on returned fields and ordering. It is clearly distinct from siblings like zfs_list_datasets and zfs_list_pools by the snapshot resource, though it never explicitly contrasts with them.

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

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

The description gives no when-to-use guidance, prerequisites, or alternative tools. It doesn't even mention the optional dataset filter that the schema exposes, so an agent gets no routing help beyond 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only the concrete example properties, not return format, the special 'all' behavior, or error conditions.

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

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

A single tight sentence, front-loaded with the verb and resource, with parenthetical examples that earn their place.

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

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

For a simple two-parameter getter with no output schema, the description is adequate to invoke the tool, but it never hints at what is returned or what the 'all' value does, leaving a mild gap for an agent interpreting 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?

Schema description coverage is 100%, so both parameters are documented in the schema itself, giving a baseline of 3. The description's example property names add slight color but no format or syntax detail beyond the schema.

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

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

States a specific verb ('Get') and resource ('a property from a ZFS pool'), and the examples (autotrim, ashift, health) concretize what a 'property' is. It distinguishes itself reasonably from zfs_pool_status / zfs_list_pools, though it does not explicitly contrast with the sibling zfs_get_property.

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 zfs_pool_status, zfs_list_pools, or zfs_get_property, nor a pointer to zfs_pool_set_property for the write side. Usage is only implied by 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=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond the annotations: the metrics are sampled over a 3-second window, implying the call blocks briefly and returns a time-averaged snapshot rather than an instantaneous value.

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

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

A single front-loaded sentence that names the resource, the metrics, and the sampling window 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 one-parameter, read-only stats tool with annotations covering the safety profile, the description is nearly sufficient. It omits whether elevated privileges are required and gives no hint of return shape, but with no output schema and a trivial input that is a minor 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?

Only one optional parameter, and schema description coverage is 100% ('Pool name (omit for all pools)'), so the schema already carries the semantics. The description adds nothing about the pool parameter, so the baseline 3 applies.

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

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

States a specific verb (Show) plus resource (ZFS pool I/O statistics) and enumerates the exact metrics returned (ops, bandwidth, latency), which is far more concrete than the sibling name zfs_pool_status alone. It does not explicitly contrast itself with zfs_pool_status or zfs_list_pools, so sibling disambiguation is left implicit.

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 zfs_pool_status or zfs_list_pools, nor any prerequisites (e.g. whether ZFS/root is needed). Usage is only inferable from the metric list, which is weaker than the 'clear context' bar.

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 this as a non-read-only but idempotent, non-destructive write. The description adds meaningful context beyond that by flagging the '(sudo)' privilege requirement, but does not describe what the property change affects or error behavior.

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

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

A single short sentence with the action, scope, privilege note, and example front-loaded. Nothing is wasted and it reads in one pass.

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 3-parameter mutation with full schema coverage and no output schema, the essentials are present (action, scope, sudo, example). It is adequate but leaves usage routing and any consequences of the change 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?

Schema description coverage is 100%, so all three parameters (pool, property, value) are documented in the schema. The description adds only an example pairing (autotrim=on), which is marginal value over the schema's own property examples.

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 ('Set a property on a ZFS pool') and scopes it to pools, which implicitly separates it from the dataset-oriented zfs_set_property sibling. It does not explicitly name or contrast against that sibling, so it falls short of a 5.

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

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

The description gives an example ('e.g. autotrim=on') but no when-to-use, when-not, or routing guidance relative to the numerous zfs_* siblings. The example clarifies value syntax, not invocation context.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds meaningful behavioral context by naming the returned content (vdev tree, scrub results, errors), which matters because there is no output schema. It stops short of noting cost of a full 'zpool status' scan on many pools.

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, front-loaded with the core action and content, with the filtering detail last. No filler or redundancy.

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

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

For a read-only, zero-required-param diagnostic tool, the description supplies the key missing piece (what status information is returned) since no output schema exists. Only minor gaps remain, such as whether health/state summary fields are included.

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

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

Schema coverage is 100% and the single optional param is fully documented in the schema ('omit for all pools'). The description's 'Optionally filter to a specific pool' restates that without adding new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb ('Show') and resource ('ZFS pool status') and enumerates the content covered: vdev tree, scrub results, errors. This clearly distinguishes it from sibling zfs_list_pools (a bare listing) and zfs_pool_iostat (performance counters).

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?

Implies usage (inspect pool health/details) and notes the optional pool filter, but gives no explicit when-to-use vs zfs_list_pools or zfs_pool_get_property, and no exclusions or prerequisites. Adequate but leaves routing to inference.

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

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

The '(sudo)' note usefully signals elevated privileges are required, adding context the annotations don't carry. However, annotations already flag this as a non-read-only, non-idempotent, non-destructive operation, and the description omits key behavior: a scrub is long-running and asynchronous (typically returns immediately), may impact I/O performance, and can be cancelled via zfs_stop_scrub.

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

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

A single tight sentence with the action front-loaded and zero filler; every clause (verb, resource, purpose, privilege) earns its place.

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

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

For a one-parameter tool with full schema coverage, no output schema, and annotations covering the safety profile, the description is nearly complete. The remaining gap is the async/long-running nature of a scrub, which an agent would benefit from knowing 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?

Schema description coverage is 100% for the single 'pool' parameter, so the schema already documents it fully. The description adds no format or naming detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Start a scrub on a ZFS pool') plus the rationale ('verify data integrity'). The contrast with the sibling zfs_stop_scrub is implied by 'Start' but never made explicit, so sibling differentiation is left to inference.

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

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

The purpose ('verify data integrity') implies when the tool is useful, but there is no explicit when-to-use, no prerequisites, and no mention of the zfs_stop_scrub alternative or the cases where a scrub is unnecessary/harmful.

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=false, idempotentHint=true, and destructiveHint=false, so the mutation/idempotency profile is covered. The description adds the meaningful detail that the operation requires sudo, but says nothing about what happens on invalid property names or whether changes take effect immediately.

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 sentence that front-loads the action and resource with no filler. It is efficient, though the parenthetical sudo note is the only extra content and more could have been said without bloat.

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

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

For a mutation tool with full schema coverage and annotations covering safety and idempotency, the essentials are present, and the sudo requirement is flagged. However, with no output schema and no error/permission behavior described, an agent lacks enough information about failure modes to be fully prepared.

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

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

Schema coverage is 100%, with each of name/value/property already documented and exemplified in the schema (lz4, 1M, off; compression, recordsize, atime). The description adds no further parameter detail, so the baseline of 3 applies.

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

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

States a specific verb (Set) and resource (a property on a ZFS dataset), which lets an agent distinguish it from zfs_get_property and, via the word 'dataset', from zfs_pool_set_property. It does not explicitly name those siblings, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus zfs_pool_set_property or zfs_get_property, nor any prerequisites beyond the parenthetical '(sudo)'. The agent must infer usage from context 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 disclose readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds the '(sudo)' marker, which is genuine auth-requirement context the annotations do not convey, though it omits what state the scrub is left in afterwards.

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 operative verb and scope front-loaded and zero filler. Every element earns its place.

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

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

For a single-parameter operation with annotations covering the safety profile and no output schema, the description supplies the essential action and the sudo requirement. It stops short of describing post-stop state or the result of the call, which is a minor gap.

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

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

Schema description coverage is 100% and the single parameter 'pool' is already documented as 'Pool name'. The description adds no naming convention, format, or validity detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Stop') and resource ('in-progress scrub on a ZFS pool'), which naturally contrasts with the sibling zfs_run_scrub. It does not explicitly name that sibling, but the stop-vs-start polarity makes the distinction unambiguous to an 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?

Usage is implied by 'in-progress scrub' — call it when a scrub is running and you want it halted — but the description never states when to use this versus zfs_run_scrub or under what conditions stopping is appropriate. No prerequisites or exclusions are given.

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