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

Goes well beyond the annotations: it discloses the exact output text, the JSON key shape (capitalised Go field names), the no-grants sentinel string, and the fact that grants are applied by daemon/reload-config. It also confirms it is read-only and daemon-answered, matching the readOnlyHint.

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?

Dense but front-loaded, leading with what the tool returns and what it excludes. Every sentence carries information (scope, usage trigger, output format, edge case, reload coupling), though the middle sentences pack multiple facts into one long clause.

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

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

With no output schema, the description fully compensates by specifying return format, JSON key names, the empty-grant case, and how grants get refreshed. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% so the schema already documents output_format, but the description adds behavioral meaning: it explains what text mode emits versus json-only output and that yaml/table/wide collapse to the same JSON. That is more than the schema conveys, though not exhaustive.

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

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

States a specific verb+resource (shows your privileged root grants) and precisely scopes what it covers versus what it does not ('It does not list which tools you may call at all'). The distinction from siblings like daemon/reload-config and docker/* is made explicit, so an agent can select it without opening a schema.

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

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

Gives explicit triggers: call before a `privileged: true` request or after a permission-denied error. It also names the exception set (docker/*, daemon/reload-config) that always needs a grant, so the when/when-not logic is complete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: text output only details the FIRST processor, json returns one object per logical CPU with architecture-dependent field names, and it explicitly discloses that it does not report sockets/cores/threads and that topology_only is inert.

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

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

Front-loaded with purpose and read-only status, and each sentence carries distinct information (output shape, architecture caveats, sibling routing). It is dense and slightly long, but nothing is filler.

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

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

With no output schema, the description carries the return-value burden and does so: it explains both the text and JSON output shapes plus the architecture-dependent field names. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond it: output_format json/yaml/table/wide all return the same JSON array, and field names vary by architecture (x86 vs ARM). It restates topology_only's no-op, which is already in the schema.

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

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

States a specific verb and resource ('Lists the machine's CPUs from /proc/cpuinfo') and immediately differentiates itself from cpu/load-average, processes/top and system/os-release. An agent can select it without opening the schema.

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

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

Explicitly routes the agent to alternatives with the selecting condition: 'For current load use cpu/load-average, for per-process CPU processes/top, for OS and kernel system/os-release.' Both when-to-use and when-not-to-use are covered.

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

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

Annotations cover readOnly/idempotent/destructive, and the description adds meaning beyond them: the exact metric semantics (runnable plus uninterruptible tasks, not a percentage), how to interpret it against cpu/list, and the concrete return shapes for text and structured formats. That is real behavioral context, not restatement.

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?

Text is dense but front-loaded with the core definition first, then interpretation, then format details, then sibling routing. Every sentence carries information an agent would otherwise have to guess.

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

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

There is no output schema, so the description appropriately supplies the return format (text example and JSON field names). Combined with the safety annotations and the interpretation guidance, an agent has everything needed to call and use it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds value beyond the schema by naming the returned fields (`1_min`, `5_min`, `15_min`) and noting that yaml/table/wide yield the same JSON as json. Minor redundancy on the default-text point keeps it from a 5.

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

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

States a specific verb (Returns) and resource (1, 5 and 15 minute load averages from sysinfo(2)), and immediately clarifies the semantics of 'load' (runnable + uninterruptible tasks, not CPU percent). An agent can distinguish it from cpu/list and processes/top without opening a schema.

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

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

Explicitly routes the agent: compare load against logical CPU count from cpu/list, use processes/top for per-process CPU, and memory/usage for memory. Both when-to-use and named alternatives are given, leaving nothing 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?

Far exceeds the annotations (destructiveHint/readOnlyHint/idempotentHint): discloses whole-crontab replacement, empty-string clearing, rejection of unparseable files leaving the old crontab intact, added final newline, 64 KiB limit, audit logging (size/lines/hash, never content), job persistence beyond session/token revocation, and container scoping. This is exactly the behavioral context annotations cannot carry.

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

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

The core read/write distinction is front-loaded and every sentence is functional, but it is a dense single paragraph carrying a lot of interleaved detail (grants, edge cases, limits, warnings) that would benefit from tighter structuring.

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

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

For a destructive read/write tool with no output schema, it covers permissions, concurrency, failure semantics, size limits, audit trails, and the container caveat. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: `content` presence triggers write vs read, `if_match` enables optimistic-concurrency protection, and `output_format: json` returns the sha256 needed for `if_match`. It also clarifies that `privileged` is ignored for your own crontab.

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

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

States specific verbs and resource: 'Reads or replaces a user's crontab' plus the listing behavior. It explicitly distinguishes itself from the sibling timers/list ('For systemd timers use timers/list'), so an agent can route correctly without opening either schema.

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

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

Gives explicit mode selection: without `content` it reads, with `content` it writes; spells out the `privileged`+`user` combinations, the grant rule requirement, and the alternative tool for systemd timers. When-to-use and prerequisites are fully covered.

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

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

Goes well beyond the annotations: it discloses the grant requirement (`allowed: true`, no unprivileged mode), the strict validate-then-apply atomicity (a misspelled key means nothing changes and an error is returned), and the side effect that sessions of removed or re-tokened users are closed, possibly the caller's own. It also states the return is free text and that it takes no parameters.

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

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

Front-loaded with the core action, and nearly every clause carries distinct information (files, affected settings, auth requirement, validation semantics, side effects, restart caveat). It is dense as a single run-on paragraph, so readability is slightly below ideal, but there is little filler.

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

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

No output schema exists, but the description states the return is free text listing what changed. Combined with the disclosed auth requirement, atomicity, session-closure side effects, and restart boundary, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Zero parameters, so the baseline is 4; the description explicitly confirms 'Takes no parameters', which is consistent with the empty schema. There is no further parameter meaning to add.

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

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

States a precise verb+resource (re-reads mcpd's config files) and enumerates exactly what gets applied: users/tokens, per-user grants, rate limits, tool timeouts. It names the concrete files (daemon.yaml, users.yaml, mcp-sudo.yaml) and is clearly distinguishable from every sibling, none of which touch daemon configuration.

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 delineates when this is the right tool versus alternatives: the files are edited on the host via linuxctl and this only reloads them, server settings (port, TLS, worker.containerized, Docker socket) still require a restart, and grants should be verified afterwards with auth/sudo-rules. Both boundaries and follow-up routing are spelled out, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: the semantics of `free` vs `used`, that `inodes: true` forces plain text and ignores other flags, and that `privileged: true` requires a grant plus a `paths:` entry or it is refused.

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?

Dense and front-loaded — the core purpose and the 'single filesystem' constraint come first, then routing, then flag behavior. Almost every clause carries information, though the single paragraph is long and would read better split.

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 return-value burden and does so: three text lines, or a JSON object enumerating path, total_bytes, used_bytes, free_bytes, use_percent plus human variants. Combined with the documented flag interactions and privilege requirements, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `free` is what non-root users can use and `used` is total minus that, and it documents cross-parameter interactions (inodes overriding output_format/human_readable) that the per-field schema descriptions do not fully capture.

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 ('Reports space on the ONE filesystem holding `path` (statfs, like `df` for a single path)') with exact scope (single filesystem, not all). It explicitly distinguishes itself from disks/mounts, disks/list, and disks/usage, so an agent can route without opening a schema.

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

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

Names each sibling alternative and the condition that selects it ('use disks/mounts for that, disks/list for block devices, disks/usage to see which folders use the space'). It also states the negative case explicitly: 'There is no all-filesystems mode; call it once per mount point.'

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

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

Annotations cover the safe-read profile, and the description adds context they cannot: root is normally required, privileged:true needs a grant, failure mode when smartmontools is absent, that a non-zero smartctl exit is not an error when JSON was printed, and that virtual disks report SMART as unsupported.

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?

Dense but front-loaded with the return value first, then prerequisites, then parameter semantics, then edge cases. Slightly long, yet each sentence carries distinct operational information rather than restating structured fields.

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

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

No output schema exists, and the description compensates by describing the return shape (smartctl JSON verbatim, keys varying by drive type) plus the error/edge-case behavior, leaving nothing an agent needs to call it correctly unaddressed.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds value beyond the schema: it clarifies `device` must be a bare kernel name never a path, and explains why `privileged` is needed (smartctl usually cannot open the device without root).

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, resource, and output form ('Returns a drive's SMART data as smartctl's JSON'), and clearly separates itself from siblings by routing I/O counters to disks/performance and device-name discovery to disks/list.

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

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

Gives explicit when-to-use routing ('find names with disks/list', 'For I/O counters use disks/performance') and prerequisites (smartmontools installed, privileged:true with a grant). Nothing about when to reach for this tool is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety burden is lower. The description still adds real behavioral context: default filtering of empty devices and RAM disks, SIZE units (bytes vs human_readable), and the privileged/container mount-point caveat. It doesn't disclose pagination or output size, but for a listing tool this is rich.

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

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

Front-loaded with purpose, then filters, then output shape, then sibling routing. Dense but every sentence carries information. The long sibling enumeration is slightly list-like but each entry is a distinct routing decision, so it 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?

No output schema exists, and the description compensates by naming the returned JSON shape (blockdevices array with nested children and field names). Combined with the filtering, unit, and privilege caveats and explicit sibling routing, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so params are documented in the schema (baseline 3). The description goes beyond by explaining the consequences of the flags — output_format json returns a blockdevices object with nested children, and privileged 'needs a grant' — adding meaning the schema's one-line descriptions don't fully convey.

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 ('Lists block devices as a tree (like lsblk)') with concrete scope (disks, partitions, LVM/dm-crypt/RAID volumes) and the data source (/sys/class/block). It explicitly routes the agent away from siblings with different purposes ('For free space or inodes use disks/free...'), making it unambiguous against disks/partitions, disks/mounts, and others.

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

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

Gives explicit when-to-use signals (empty devices hidden unless all:true, containerized deployments need privileged:true) and names seven alternative sibling tools with the condition that selects each (free space, folder sizes, mount table, partition boundaries, I/O counters, SMART). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real context: it reads the daemon's own mount namespace, container usage requires a privileged grant, and it documents an edge case (returns null rather than [] when nothing matches). This is behavioral information not present in annotations or schema.

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

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

Front-loaded with the core purpose and data source, then constraints, then output shape, then sibling routing. It is a dense single block but nearly every clause carries actionable information; only the textual line-format example is arguably illustrative filler.

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

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

No output schema exists, but the description compensates by describing both the text line format and the JSON array shape (device, mount_point, fs_type, options) plus the null-when-empty behavior. Combined with the routing and privilege notes, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds meaning beyond it: fs_type is an exact match with no globs, privileged needs a sudo grant or is refused, and json vs text output behavior (with the null edge case). It enriches the parameters rather than merely restating them.

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: 'Lists mounted filesystems (device, mount point, type, options)' with an explicit data source (/proc/thread-self/mounts) and ordering. It also names the neighboring tools it is not ('For block devices use disks/list, for the space used on a mount disks/free'), so an agent can disambiguate without opening a schema.

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

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

Explicitly routes to alternatives: disks/list for block devices and disks/free for mount usage. It also states the precondition for host mounts in a container (privileged: true, which needs a grant), covering when-to-use and a key constraint rather than leaving it to inference.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description goes well beyond them: native /sys/class/block read path, the 512-byte sector-size assumption, the error case for a named disk with no partitions, and both output shapes (text table vs indented JSON). This is the kind of behavioral context annotations cannot express.

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

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

Front-loaded with the core purpose and read-only note, then the device semantics and alternatives follow in a logical order. It is dense but nearly every clause carries information; only the device restatement slightly duplicates the schema.

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

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

With no output schema, the description supplies the return shape (text table or JSON array with named fields), the key assumption (512-byte sectors), and the error behavior. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the schema already documents 'device' as a parent disk name, so the description's re-statement is redundant. It does add value by explaining the omission default and by disclosing an accepted but schema-undocumented output_format parameter, which meaningfully expands the invocation surface.

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 ('Lists the partitions of a disk') plus the exact data returned (start sector, size in sectors and bytes) and the data source (/sys/class/block, no fdisk). It explicitly distinguishes itself from disks/list and disks/mounts, which cover label/UUID/filesystem information.

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

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

Gives explicit when-not guidance ('does not report partition type, label, UUID or filesystem: use disks/list or disks/mounts') and routes the agent to disks/list for discovering device names. It also clarifies the meaning of the optional device argument, including the default behavior when omitted.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description nonetheless adds meaningful behavior: values are cumulative since boot (not rates), no %util or await exist, loop*/ram* are excluded by default, and an unknown device yields 'no such block device'. The one gap is that it never describes pagination or output size limits for the all-devices case, which keeps this 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?

It is dense but front-loaded: the first sentence establishes source and payload, then semantics, then caveats, then alternatives. Almost every clause carries information, though the parenthetical field enumeration ('major, minor, device_name, ...') is slightly over-long for what it conveys.

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 semantics itself, and it does: text table by default, JSON/YAML array of 14 named fields, plus cumulative-vs-rate interpretation. Combined with device filtering and error behavior, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: 'a name such as sda', the exact default-filtering rule (all except loop* and ram*), the error string for an unknown name, and that yaml means real YAML with 14 named fields in JSON/YAML mode.

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

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

The description names a specific verb and resource ('Returns block-device I/O counters from /proc/diskstats') and enumerates exactly which counters are returned. It also distinguishes itself from siblings by naming disks/free (capacity), disks/health (SMART) and disks/list (device discovery) as different tools.

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

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

It states when this tool is the wrong choice ('For capacity use disks/free, for SMART health disks/health'), how to obtain a rate (sample twice and subtract), and how to resolve a device name (find them with disks/list). Both the use case and the alternatives are explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: 60 s per-user result caching, the 300 s shipped vs 30 s default timeout, silent skipping of unreadable directories (and the resulting possible under-count), hard-link/symlink handling, and the `privileged` grant requirement via mcp-sudo.yaml. The one meaningful gap is that it doesn't say whether `exclude` or `threshold` interact with the cached result set, but overall this is unusually rich 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?

The purpose and sibling routing are front-loaded, followed by dense but relevant behavioral and parameter detail. Every sentence carries information, though the single long paragraph is heavy and could be broken up for scannability.

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

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

For an 11-parameter tool with no output schema, the description compensates well: it explains default vs max_depth vs all output modes, the text trailer ('Total size of PATH: N'), and the JSON object shape including directory_sizes only when max_depth > 0. Nothing an agent needs to call or interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by tying parameters to output behavior ('By default the reply is one grand total; max_depth: N also lists directories...; all: true adds a per-file list (text output only)') and clarifying that allocated blocks are the default unit unless apparent_size. It leaves `threshold`, `separate_dirs`, and `one_file_system` entirely to the schema, so it isn't a full complement.

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 ('Measures how much disk space a directory tree uses') and explicitly frames it against siblings, calling out `disks/free` for filesystem free space and `files/find` for individual big files. An agent can distinguish this from the other disks/* tools without opening any schema.

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

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

Explicitly names the two alternatives (whole-filesystem free space -> `disks/free`; individual big files -> `files/find` with `size`) and the conditions that select them. This is textbook when-to-use/when-not guidance.

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

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

Annotations already cover readOnly/idempotent, but the description adds substantial behavioral context beyond them: it always runs as root with no privileged argument, caller requires grant allowed: true or it is refused, empty-result text differs by format, and JSON returns [] when empty. These are exactly the operational facts an agent cannot infer from 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?

Front-loaded with purpose and scope, and every sentence carries routing, filtering, or auth information. It is dense and somewhat long for a listing tool, and the output-format behavior is described in two passes (text hint line, then json/yaml/table/wide), which is slightly redundant.

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

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

For a five-parameter read-only listing tool with no output schema, the description covers filtering semantics, both return shapes (text block + hint line, or JSON array with named fields), empty-result behavior, and the authorization prerequisite. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics (state implies all, limit returns the newest N) and worked examples (glob 'web-*') that clarify how the filters interact. It does duplicate some schema text, keeping it from a 5.

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

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

States a specific verb (Lists), resource (Docker containers), and mechanism (Engine API on the local socket, no docker CLI), then names the exact fields returned. It explicitly distinguishes itself from docker/logs, docker/manage, docker/exec, and the docker-container:// status resource, so an agent can route correctly without opening any schema.

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

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

Gives explicit routing rules: 'For logs use docker/logs, to start or stop docker/manage, for one container's details the docker-container://<name>/status resource.' It also states the condition that selects each filter mode (all vs. state vs. pattern vs. limit) and notes the grant's containers: list does not apply here.

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 destructive/non-readonly/non-idempotent, but the description goes well beyond them: no TTY/stdin/follow, runs as root at the socket, as the image's user unless `user` is set, non-zero exit is not a tool error, timeout interaction with the worker limit and continued execution after timeout, and a 1 MiB output cap. This is exactly the extra behavioral context that matters for a high-risk tool.

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

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

Dense and front-loaded: purpose, then risk profile, then argument semantics, then timeout/output behavior, then sibling routing. It is long, but each sentence carries distinct operational information rather than filler.

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

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

No output schema exists, yet the description documents the return shape for both text ('Exit code: N' plus output) and json (container, id, command, exit_code, running, stdout, stderr). Combined with risk, timeout and argument semantics, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema does not: `command` is an argv array rather than a shell line (with an sh -c example), and `timeout` is bounded by the worker limit which can override it. These nuances materially affect correct 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+resource+scope ('Runs ONE command inside a running container and returns its stdout, stderr and exit code') and immediately narrows it ('no TTY, no stdin, no follow'). It names the siblings it is not (docker/logs, docker/manage), so an agent can route correctly without opening schemas.

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

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

Explicitly routes to alternatives ('To read logs use docker/logs, to manage the container docker/manage') and states the conditions for use: refused unless the grant has allowed: true, and the grant-list requirement. Both when-to-use and when-not-to-use are covered.

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

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

Goes well beyond the annotations: discloses that untagged layers are hidden unless all:true, how untagged images render (<none>:<none>), that it always runs as root with no privileged argument, and that it is refused unless the grant has allowed:true. That is auth and filtering behavior the readOnly/idempotent hints do not convey.

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

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

Front-loads purpose, then filtering semantics, then output shape, then routing and auth. Information-dense, but it is one long paragraph and the root/refusal clause is buried at the end when it is a critical operational constraint.

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

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

With no output schema, the description fully compensates by describing both the text format (tag lines with ID | Size | Created) and the JSON object shape, plus empty-result behavior ([]). Combined with sibling routing and the root requirement, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: pattern is a glob over tag or repository with concrete examples, all:true controls intermediate/untagged visibility, and output_format's array is itemized by field (id, full_id, repo_tags, size_bytes, containers, labels). Field-level return detail exceeds 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 (Lists) and resource (Docker images) with scope (on the local socket via Engine API) and enumerates what is returned (tags, ID, size, creation time). It also carves itself out from siblings by naming docker/prune, docker/containers and the docker-image inspect resource.

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

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

Explicitly routes the agent: deletion goes to docker/prune (target images, dangling only), containers go to docker/containers, and per-image config goes to the docker-image:// resource. The when-to-use boundary is unambiguous.

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

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

Annotations already declare the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds substantial context beyond them: interleaved stdout/stderr ordering, never-follow semantics, a 1 MiB cap with the oversized tail silently cut at the END (so newest lines can be lost), the auth/grant refusal condition, and the empty-result message. This is the kind of operational detail that prevents silent surprises.

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

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

Front-loaded with the core purpose and alternatives, and every clause carries information (defaults, truncation, auth, output shape). It is dense and semicolon-heavy, which slightly reduces scanability, but there is essentially no filler to cut.

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

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

For an 8-parameter read tool with no output schema, the description covers everything an agent needs: return format (plain text vs `output_format: json` fields), empty-result behavior, auth/grant requirements, and the lossy truncation case. Nothing material is left to inference.

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 each parameter already carries its own description; the description still adds value by disclosing interaction and edge-case semantics, e.g. "stdout and stderr default to true (both false returns nothing)" and tying `lines` to the truncation cap. It reinforces rather than merely repeats the schema, though it does not add syntax detail beyond the timestamps example already in the schema.

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

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

States a specific verb and resource ("Reads one container's recent logs") and immediately anchors it against a named sibling ("the container counterpart of logs/journal-control"). The ordering, default line count, and no-follow constraint are all specified, so the agent knows exactly what this tool returns.

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 away to alternatives: "To run a command use docker/exec; for host logs logs/journal-control." It also states the preconditions that gate invocation ("Only containers in the grant's containers: list; always runs as root, refused unless the grant has allowed: true"), which is exactly the when/when-not guidance an agent needs.

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?

Far exceeds what annotations provide: authorization model (name and ID checked, empty list refuses everything, runs as root, no privileged argument, requires allowed: true), the 10 s stop grace, and remove's deliberately fenced behavior (never sends force or volume removal, running container refused, anonymous volumes kept). This is exactly the mutation context an agent needs, which annotations alone (destructiveHint=true) cannot supply.

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

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

Front-loaded with purpose and action list, then layered constraints, edge cases, output format, and sibling routing. Dense but nearly every clause carries unique information; slightly long for a 3-parameter tool.

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 supplies both the text format ('Container NAME (ID12): stop succeeded.') and the JSON fields (container, id, action, result). Authorization, irreversibility, and no-op semantics are all covered, leaving nothing an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so container/output_format semantics are already documented. The description restates 'container is a name, full ID or ID prefix' and the JSON return fields, adding little beyond the schema; baseline 3 is correct when the schema does the heavy lifting.

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

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

Opens with a specific verb and resource ('Changes a container's lifecycle') and enumerates all seven actions. It explicitly positions itself as 'the container counterpart of `services/manage`', so an agent can distinguish it from the sibling without opening either schema.

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

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

Explicit routing at the end: bulk cleanup → docker/prune, run a command → docker/exec, check state first → docker/containers. It also states preconditions (grant containers list, allowed: true) and the no-op cases ('start on a running or stop on a stopped container reports unchanged').

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

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

Annotations already declare readOnly/destructive/idempotent/openWorld, so the safety profile is covered. The description adds context beyond them: the root-execution requirement, refusal unless the grant has `allowed: true`, and the text-mode rendering (`Attached: (nothing)` for empty networks). These are genuine behavioral details, though return-shape nuances could be richer.

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?

Dense but front-loaded: purpose and scoping lead, then outputs, then sibling routing. Nearly every sentence earns its place, though the single long paragraph packs many clauses and could be slightly tighter.

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

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

There is no output schema, yet the description enumerates the JSON object fields (name, id, full_id, driver, scope, created, internal, attachable, ingress, ipam_driver, subnets, gateways, containers, options, labels), so the agent knows the return shape. Combined with sibling routing and auth requirements, 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 coverage is 100%, so baseline is 3, but the description adds real meaning: `pattern` is a glob on the name, `driver` is an exact driver match with valid values (bridge, host, none, overlay, macvlan), and it documents what `output_format: json` returns. This goes beyond the schema's own descriptions.

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 ('Lists Docker networks') and enumerates exactly what is returned: driver, scope, subnet, gateway, and attached containers with addresses. It actively distinguishes itself from the host-interface siblings (`network/*`, `network://`) and other docker tools, so an agent can identify it without opening the schema.

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

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

Explicitly routes the agent: host interfaces/routes go to `network://` resources and `network/*` tools, unused-network removal is `docker/prune` (target `networks`), and single-network detail is the `docker-network://<name>/inspect` resource. When-to-use and when-not-to-use are both spelled out.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: needed grant (`prune:` list containing the target, else refused before deletion), root execution with no `privileged` argument, `allowed: true` requirement, and the 30 s worker timeout that can end the call while the Engine keeps pruning. It also describes the exact return text and the JSON shape, which the annotations cannot convey.

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

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

One dense paragraph, front-loaded with the target enumeration and the irreversibility warning before the routing and output detail. Every sentence carries information, though the return-format sentence is long enough that a human reader would benefit from splitting it out.

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

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

There is no output schema, and the description compensates by describing both text and json return shapes. Combined with grant/permission requirements, timeout caveats, irreversibility, and sibling alternatives, an agent has everything needed to call this correctly on the first try.

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 genuine semantics beyond the schema: the volume distinction (anonymous/unused only; named volumes never touched) and the concrete json fields (target, deleted, count, space_reclaimed_bytes) plus the fact that networks report no size. That is more than restating the enum.

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 (deletes) and resource (unused Docker objects), then enumerates the exact five targets and each one's scope (stopped containers, dangling images, anonymous unused volumes, unused networks, build-cache). It explicitly separates itself from docker/manage (`remove`) and the listing tools, so an agent can disambiguate without opening any schema.

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

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

Gives explicit when-to-use routing (prune for bulk unused objects; `docker/manage` with `remove` for one named container) and when-not (named volumes are never touched). It also explains the ordering prerequisite that pruning containers is what makes images dangling, which is real operational guidance, not filler.

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

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

Beyond the annotations (which already declare read-only/idempotent/non-destructive), it discloses that the tool always runs as root, has no privileged argument, and is refused unless the grant has allowed: true. It also distinguishes its behavior from docker/prune (anonymous unused volumes only) and documents the empty-result and output-format 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?

Purpose is front-loaded and every sentence earns its place: read-only scope, glob semantics, output formats, the prune distinction, sibling routing, and the root/grant requirement are all non-redundant and useful.

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

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

With no output schema, the description still documents return values and the empty case, plus auth requirements and alternatives. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the json output shape (an array of objects with name, driver, mountpoint, created, scope, labels, options, in_use_by) and the [] empty case, though the pattern glob is already documented in 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 (Lists) and resource (Docker volumes) plus exactly what is returned: driver, mountpoint, and mounting container names. An agent can immediately distinguish it from docker/containers, docker/images, and docker/networks.

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 to alternatives: the docker-volume://<name>/inspect resource for single-volume details, docker/containers for containers, and docker/prune target volumes for removal. It also clarifies the read-only boundary ('volumes are never created or removed here').

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 mutating/destructive/idempotent, but the description adds substantial context beyond them: symlinks are never followed and any symlinked component is refused, recursive runs skip and report symlinks, GNU numeric-mode semantics (4-digit vs 5-digit setuid handling), the exact return format for single and recursive runs, and that recursive runs are non-atomic with possible partial success.

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

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

Front-loads the core purpose and the sibling routing, and almost every clause carries distinct information. It is dense and somewhat run-on with heavy semicolon chaining, which slightly hurts scanability, but little is wasted.

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

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

For a complex mutating, non-atomic tool with 4 parameters and no output schema, the description is complete: it discloses return formats, symlink policy, elevation requirements, mode semantics, and partial-failure behavior, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds real meaning: it clarifies numeric vs symbolic mode behavior (a bare `755` is octal, 4 vs 5 digits control setuid/setgid), and that `privileged` requires both a grant in mcp-sudo.yaml and a `paths:` entry. This meaningfully elaborates on the schema.

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

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

States a specific verb and resource ('Changes a file's or directory's permission bits (chmod)') and explicitly distinguishes itself from siblings by naming `files/chown` for owner/group and `files/list` to check results. An agent can identify and route to it without opening the schema.

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

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

Explicitly states when to use alternatives (`files/chown` for owner/group, `files/list` to verify) and the condition that requires elevation (`privileged: true` plus a grant and `paths:` entry for files you don't own). Nothing is left to inference.

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

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

Goes well beyond the annotations (destructive/idempotent/not-readOnly): it discloses that symlinks are never followed and any symlinked component is refused, that recursive runs skip and report symlinks, that ownership change needs privileged elevation, and that recursive runs are non-atomic. This is exactly the class of mutation-risk detail the description should carry.

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

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

Purpose and mutating nature are front-loaded in the first clause, and each subsequent sentence carries distinct value (symlink semantics, privilege requirement, return format). It is dense and somewhat clause-heavy, but nothing is filler.

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

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

With no output schema, the description still explains return values ("PATH: old -> new", `unchanged`, recursive per-entry lines plus a summary). Combined with the annotations covering the safety profile, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters (baseline 3). The description adds real meaning beyond the schema, though: the owner format variants, that names are resolved via /etc/passwd and /etc/group, and that an unknown name fails with "no such user".

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: "Changes a file's or directory's owner and/or group (chown)." It also distinguishes itself from siblings by routing permission-bit changes to `files/chmod`, so an agent can differentiate without opening a schema.

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

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

Explicitly names alternatives and the condition that selects them: use `files/chmod` for permission bits and `files/list` to check the result. It also states the prerequisite (privileged: true with a grant and paths entry) for ownership changes, leaving little 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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true): not atomic, parent dirs created at 0755, new file 0644, existing file keeps mode, empty content only touches and never truncates, privileged mode needs a grant plus a paths entry covering the path and refuses symlinks, and the exact success/failure return strings.

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

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

One dense paragraph that front-loads the core behavior (whole-file write, replacement, non-atomic) before alternatives and edge cases. Every sentence carries information, though the volume makes it slightly heavy for a three-parameter tool.

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 supplies the return contract (one success line, plain-text failures), plus privileged-mode prerequisites and symlink behavior. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: content is text with no trailing newline appended, path must be absolute, and privileged requires both a grant and a covering paths entry. It largely mirrors the schema for path but enriches the privileged and content semantics.

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 with scope: 'Writes a whole file: creates it, or REPLACES the content of an existing one entirely.' It immediately distinguishes itself from the closest sibling by noting it replaces entire content versus files/update which changes parts.

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 to alternatives with conditions: use files/update to change part of a file, files/list or files/find to check existence, files/chmod/files/chown to set mode or owner. It also clarifies the empty-content touch semantics versus truncation, leaving nothing 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?

Goes well beyond the readOnly/idempotent annotations: it discloses that symlinks are never followed (reported as inode/symlink), that directories/devices/fifos/sockets report as inode/..., the 8 KiB detection window, and that privileged mode requires a grant plus a `paths:` entry or is refused. It also states the reply shape (one plain-text line, no output_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?

Front-loaded with the core behavior and organized by purpose, alternatives, and return format. It is densely packed with semicolon-chained clauses, but virtually every clause carries distinct information, so little is wasted.

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

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

With no output schema, the description compensates by stating the return format ('always one plain-text line, no output_format'). Combined with the symlink/special-file behavior and privileged prerequisites, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and both parameter descriptions already state 'absolute path' and the privileged grant/paths requirement, so the description largely restates what the schema provides. The added 'otherwise refused' phrasing is marginal value, 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+resource ('Returns a file's MIME type') plus the exact detection mechanism ('like `file -b --mime-type`, detected natively from its first 8 KiB'). It explicitly differentiates from siblings by naming files/read and files/list and what each is for.

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

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

Gives an explicit trigger ('Use it before `files/read`, which refuses binary files') and routes the other use cases away to named alternatives: files/list for size/permissions/ownership, files/read for contents. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, yet the description still adds substantial behavior: never follows symlinks, the /proc /sys /dev /run skip rule (and its path-dependent exception), the absence of a result cap, the 30 s worker timeout, and silent skipping of unreadable directories. This is exactly the contextual detail annotations cannot express.

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?

Well front-loaded: purpose and safety first, alternatives next, then filter semantics, syntax, and output format. It is dense and every section earns its place, though the syntax recap is lengthy for a schema that already documents the same rules.

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 9 optional params and no output schema, the description still specifies the filter combination rule, the destructive-risk caveat, and the exact return shape (per-line SIZE PATH sorted by path, empty output = no match; json array of path/size/type). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds non-schema semantics: all filters are ANDed and none is required, plus the relative-vs-absolute mtime/size operators and max_depth defaults. Most per-parameter syntax restates the schema, so it is value-adding but partly redundant.

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

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

States a specific verb (searches) and resource (a directory tree) plus the filter axes (name, type, age, size) and the `find` analogy. It positively distinguishes itself from `files/list` (single known directory) and `disks/usage` (space consumers), so an agent can route without opening a schema.

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

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

Explicitly names the alternatives and their conditions ('Use `files/list` to see one known directory and `disks/usage` to see which folders take the space'), and warns when a filter is mandatory to avoid an unbounded scan. When-to-use and when-NOT-to-scan-without-a-filter are both covered.

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

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

Goes well beyond the readOnly/idempotent annotations: not recursive, no entry cap, symlinks shown but never followed, root calls require a `paths:` entry in mcp-sudo.yaml, and the exact empty-result markers ('Directory is empty.' / []) are disclosed.

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

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

Front-loaded with the core semantics and every clause carries information (scope, exclusions, failure mode, output format). It is dense to the point of being a single long paragraph, which slightly hurts scanability.

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

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

With no output schema, the description compensates by enumerating the JSON return fields and the text/empty formats; all 10 parameters and the recommended fallbacks are covered, so an agent can call it correctly without further context.

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 cross-parameter behavior the schema does not state: the list of JSON object fields returned, that non-text formats all yield the same JSON, and the symbolic-link non-following guarantee tied to the listing.

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 (lists the entries of ONE directory) with the exact scope and output shape ('like ls -l'), and explicitly names the sibling tools it is not (files/find, disks/usage, files/filetype) with the condition that selects each.

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

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

Gives explicit routing rules for alternatives (recursive/filtered → files/find, total size → disks/usage, MIME → files/filetype) and a concrete remediation path for failure ('on permission denied retry with privileged: true if granted').

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond them: the 10240-byte truncation with a `[WARNING: File truncated ...]` line, no streaming (one call reads into memory), line-mode failure for lines over 64 KiB, error on start_line past end, empty string for empty files, and the grant/paths requirement for privileged. This is rich, non-obvious 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?

Dense but front-loaded: reads as raw text, read-only, absolute path first, then routing, then selection semantics, then edge cases. Every sentence carries information, though the prose is packed tightly enough that it borders on overloading a single paragraph.

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 tool with no output schema, the description covers return format, truncation, error conditions, and privilege requirements completely. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully adds precedence rules not fully captured by the schema: start_line/end_line take precedence over offset/limit, start_line alone reads to end, end_line alone starts at line 1, and offset without limit caps at 10240 bytes. Useful cross-parameter semantics, though most individual param meaning is already in the schema.

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

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

States a specific verb and resource ('Reads a text file and returns its contents as raw text') and explicitly scopes the return format ('no line numbers or metadata'). It also names three siblings (files/find, files/list, files/filetype), so an agent can distinguish it without opening any schema.

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

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

Gives explicit routing to alternatives: 'To find a file use files/find, for size or mode files/list, to check whether it is binary files/filetype'. This is when-to-use-this-vs-others guidance with concrete alternatives, not just implied 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 and idempotentHint=false, but the description adds non-atomicity, that mode and owner are preserved, the exact return strings, the absence of a diff, and the privileged-grant requirement. It also discloses subtle behavioral edge cases (trailing newline ignored, end_line clamped, start_line past end appends) that no annotation covers.

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

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

Front-loads purpose and alternatives before edge cases, and nearly every sentence carries essential semantics. It is on the long side, but the density of non-obvious behavior (clamping, newline rules, no insert/delete mode) justifies most of the length.

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

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

With no output schema, the description supplies the return values directly and covers preconditions (file must exist, path absolute, parent dirs not created), mode/owner preservation, and failure modes for privileged edits. Nothing an agent needs to invoke it correctly appears missing.

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

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

Schema coverage is already 100%, yet the description still adds semantics the schema lacks: append precedence over line ranges, that start_line AND end_line are jointly required and 1-indexed with end_line >= start_line, the newline handling on append, and the privileged grant mechanics. This meaningfully exceeds the schema text.

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

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

States a specific verb (Edits), resource (file), and the two distinct modes (append vs. replace line range) in the first sentence. Explicitly contrasts itself with `files/create` for whole-file writes and `files/read` for inspecting lines, so an agent can distinguish it from siblings without opening a schema.

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

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

Names both alternatives and the condition that selects each ('To write a whole file use files/create; to see the lines first use files/read with start_line/end_line'). It also spells out when append mode applies versus line-range mode, including that append wins over a supplied range.

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

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

Goes well beyond the annotations (destructiveHint=true, readOnlyHint=false) by disclosing that reads need no grant, writes require privileged:true plus a sysctl.write_keys grant from mcp-sudo.yaml, are refused outside those globs, last only until reboot, and are never persisted to /etc/sysctl.d. This is exactly the mutation-risk context an agent needs.

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

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

Dense but front-loaded: read semantics first, then write semantics, then persistence caveats, then sibling routing. Every clause carries information, though the single long paragraph could be broken up slightly for scanability.

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

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

For a complex dual-mode tool with no output schema, the description covers return format ('key = value' lines, subtree listing, uncapped read_all output), permission model, persistence, and alternatives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including dotted/slash key forms and the read_all/key dependency. The description largely reinforces that content, adding only minor framing (reply shows resulting value), 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 precise verb+resource: reads or writes a kernel parameter (sysctl) via /proc/sys, and immediately disambiguates read vs write mode by the presence of `value`. An agent can distinguish this from siblings like system/os-release or memory/usage 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 elsewhere for adjacent needs ('For OS and kernel version use system/os-release, for memory figures memory/usage') and states the condition governing read_all ('only when key is empty'). Reading vs writing selection is spelled out with prerequisites for each.

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

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

Annotations already cover read-only/idempotent safety, but the description adds substantial behavior: output is truncated to the last 30 KiB with a warning prefix, cannot be paged, fails under dmesg_restrict unless privileged with a grant, and output_format is accepted but ignored. These are real operational constraints not derivable from 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?

Dense but front-loaded: purpose first, then truncation constraint, then the filtering parameter, then the failure mode, then the sibling routing. Every sentence carries distinct, actionable information with 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?

With no output schema, the description carries the return-value burden and does so: plain text, 30 KiB truncation, non-pageable. Combined with the failure-mode and routing guidance, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so the meaning of level, privileged, and output_format is already documented in the schema, including the enum values and the 'ignored' note. The description restates the level enum and the privilege/grant requirement without adding syntax or format detail 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 and resource ('Reads the kernel ring buffer') and names the wrapped command, so an agent knows exactly what is returned. It also distinguishes itself from siblings by pointing to logs/journal-control, logs/logins, and disks/health for other log sources.

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

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

Gives explicit routing rules: journal-control for older history/service logs, logins for login records, disks/health for drive faults. It also states when privileged is required (kernel.dmesg_restrict=1) and how to narrow output with level.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: ordinary users see only their own entries without root or systemd-journal/adm group membership, privileged:true is needed in containers because journalctl lives only on the host, and boots are scoped with offset precedence. These are non-obvious operational constraints an agent must know.

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

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

A single dense paragraph that front-loads what the tool does before constraints and alternatives. Nearly every clause earns its place; it is long for nine parameters but not 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 9-parameter read tool with no output schema, the description covers defaults, output format semantics, permission/privilege prerequisites, and sibling routing. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: boot_offset 'takes precedence over boot', lines is 'the only size limit', and the JSON output is 'one JSON object per line, not an array'. The since/until syntax examples largely duplicate 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 the specific verb+resource ('Reads the systemd journal') and even names the underlying command it wraps. It explicitly distinguishes itself from four siblings by use case (logs/dmesg for kernel, logs/logins for logins, docker/logs for containers, services/list for unit state).

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?

Explicit routing rules to alternatives are given for each overlapping scenario, plus when root/group membership matters and when privileged:true is required. No conditions are left for the agent to infer.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: raw text rather than JSON output, the trailing 'wtmp begins...' line being dropped, empty history returning an empty line, and the root/grant requirement for failed logins.

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?

Dense and front-loaded: the primary purpose and mode mapping come first, then output caveats, then routing. Every sentence carries information, though the parenthetical tool-name references make it slightly heavy to parse.

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

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

With no output schema, the description compensates by explicitly stating the return is raw text, how the summary line and empty cases behave, and what host dependencies must exist. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters including the enum are already documented. The description restates limit ('keeps the N most recent entries') and user ('filters by username') but adds no format or ordering detail 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 and resource (login history / failed login attempts) and names the two underlying tools it wraps (`last` and `lastb`), so the agent knows exactly what is returned and which mode maps to which behavior.

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

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

Explicitly routes the agent elsewhere when appropriate: 'For account details use users/list, for authentication messages logs/journal-control.' It also states the host prerequisite (`last`/`lastb` must be installed) and the grant requirement tied to the privileged parameter.

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/idempotent/destructive=false, so the safety profile is covered; the description adds genuinely new behavioral facts, notably that `detailed` is silently ignored with output_format json and that `human_readable` is ignored in json/yaml/table/wide output. That silent-ignore behavior is exactly the kind of trait structured fields don't capture.

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

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

Purpose and read-only status are front-loaded, and the dense middle section on formats and formulas is all decision-relevant rather than filler. It is heavier than it needs to be for a three-flag read tool, which keeps it short of a 5.

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

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

There is no output schema, so the description carries the return-shape burden and does it fully: it describes the text `free`-like table, the JSON object and its keys, byte vs human-readable units, and the raw-meminfo alternative. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the exact formula for `used`, that `available` maps to the kernel's MemAvailable, the enumerated JSON keys, and the cross-parameter interactions between detailed/human_readable and output_format.

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 ('Reports memory and swap use from /proc/meminfo') and explicitly separates itself from siblings by naming processes/top, processes/list and cpu/load-average as the right tools for adjacent concerns. An agent can pick this without opening any schema.

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

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

Routes the agent explicitly: per-process memory goes to processes/top or processes/list, CPU load goes to cpu/load-average. It also states when to use each mode (detailed for raw /proc/meminfo, json for structured output), leaving nothing 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial behavioral context beyond them: the cache's staleness limitation, IPv6 exclusion, the namespace scoping, and the null-vs-[] return quirk.

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

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

Front-loaded with the core purpose, then scope, limitations, alternatives, and return shape in a tight sequence. Every sentence carries distinct information; none is padding.

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

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

With no output schema, the description fully specifies the return contract – always JSON, an array of objects with named fields, and null (not []) when empty. Combined with the cache caveats, nothing an agent needs to call and interpret this tool 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 schema already documents `interface` as the exact interface name with omission meaning all. The description's elaboration ('exact device name (eth0); omit it for all') largely restates the schema, so baseline 3 applies.

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

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

States a specific verb+resource (shows the kernel's ARP cache), its exact data source (/proc/net/arp), and its scope (daemon's network namespace). It explicitly distinguishes itself from network/connections and network/ping, so an agent can select it without opening a schema.

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

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

Names the alternatives explicitly with conditions: network/connections for sockets/connections and network/ping for reachability. It also tells the agent when NOT to expect results (cache, not a scan; IPv6 excluded), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial undisclosed context: data sourced from /proc/net, unix/raw sockets excluded, other users' PIDs require `privileged: true` plus a grant, and an invalid state raises an error listing valid names. It stops short of describing ordering or performance characteristics on large hosts, keeping it just below the top.

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

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

Front-loads the core purpose and is free of filler sentences, but it is a dense single block of parenthetical-heavy clauses (state list, privilege caveat, output fields, sibling routing), which costs some scannability.

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

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

With no output schema, the description still documents return shape: text mirrors `ss -tuanp` columns and JSON returns an array of objects with netid, state, recv_q, send_q, addresses, uid, inode and processes, plus `[]` when empty. Combined with the privilege and error behavior notes, nothing an agent needs is missing.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description goes well beyond the schema: state is case-insensitive with `_`/`-` interchangeable, valid enumerations and the connected/synchronized groups are listed, and `port` is clarified as matching local OR peer port.

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

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

Opens with a specific verb+resource ('Lists TCP and UDP sockets in every state with their owning processes') and anchors it to a familiar tool via 'like `ss -tuanp`, read natively from /proc/net'. It also explicitly scopes out unix and raw sockets, so an agent can immediately distinguish it from network/arp and the other network 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?

Names concrete alternatives with conditions: 'For the ARP cache use `network/arp`, for interfaces and IPs the `network://interfaces` resource, for process details `processes/list`.' Usage is triggered implicitly by the state/port filters and the privileged note, leaving little to inference.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description goes well beyond them: method is sent as given so POST/PUT/DELETE mutate remote state, redirects follow up to 10, non-2xx is not an error, the 10 s default timeout and 30 s worker cap, body truncation at max_body with truncated=true, insecure skipping TLS, the proxy/policy interaction (network: policy in mcp-sudo.yaml applies to every call and redirect hop), and audit-log redaction. This is unusually complete 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?

Front-loads the core purpose and the NOT-read-only warning, then stacks behavioral facts, and closes with sibling routing — a sensible order. It is dense and long for a one-call tool, but nearly every clause carries distinct operational information, so little is wasted.

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

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

For a 7-parameter tool with a nested headers object and no output schema, the description still enumerates the returned JSON fields (status_code, status, headers, body, truncated) plus the ignored output_format. Combined with the safety, timeout, truncation, and policy notes, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully enriches it: method is sent as given with GET default, timeout is whole seconds with the 30 s cap, and max_body's default (1 MiB) and max (10 MiB) with the truncated flag tie the parameter to observable output. It adds real meaning over the schema rather than restating it.

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

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

States a specific verb+resource ('Makes one HTTP(S) request') and the exact return shape (status, headers, body). It actively distinguishes itself from siblings by routing DNS to network/nslookup, TCP reachability to network/ping, and local files to files/read — an agent can pick this tool without opening any other 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 names three alternative tools and the condition that selects each (DNS, TCP reachability, local files). It also sets usage context: a non-2xx status is not an error, and one call is one request. Nothing about when to reach for this tool is left to inference.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds genuinely new behavior: queries go off-host, answers may come from a local cache, the resolver is fixed, and failures surface as a specific error ('HOST: no such host'). It even discloses the exact return payload shape and MX formatting.

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

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

Front-loaded with the core purpose and dense with useful detail, and every clause earns its place (default-ANY semantics, error string, sibling routing). It is a long single paragraph, but there is no filler or repetition.

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?

Even without an output schema, the description fully specifies the JSON return shape ('host' plus 'records' of 'type'/'value'), the MX value format, and the empty-records vs. non-existent-name distinction. Nothing an agent needs to call or interpret it is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning beyond the schema: record_type is case-insensitive, default ANY is not a DNS ANY query but a sequential multi-type lookup, unsupported types are rejected, and host must be a name rather than an IP.

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 ('Resolves DNS records for a hostname') and immediately scopes it ('through the host's resolver, a DNS server cannot be chosen'), which no sibling shares. An agent can distinguish this from network/ping, network/curl, and network/trace-path without opening their schemas.

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

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

Explicitly routes the agent: 'To test reachability use network/ping, to fetch a URL network/curl.' It also states when-not conditions — IP addresses are not reverse-resolved and SOA/PTR/SRV types are rejected — leaving nothing 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?

Goes well beyond annotations: notes it connects off-host, honors the user's network: policy in mcp-sudo.yaml, that failure is not a tool error but a JSON success:false, that latency includes DNS, and that it is a single attempt with no loss statistics. Annotations only signal read-only/idempotent/open-world; the description adds the operational realities an agent needs.

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

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

Dense but front-loaded: behavior, caveats, then sibling routing. Nearly every clause earns its place, though it is information-heavy in one paragraph and could be split for scanability.

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

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

For a 3-param network probe with no output schema, it covers return fields (host, port, success, latency_ms, error), the failure model, policy interaction, and alternatives. 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 coverage is 100%, so baseline is 3; the description adds non-obvious semantics the schema omits - port defaults to 80 because a listening port is required, timeout is whole seconds with default 5, and failure semantics attach to the connect result. Adds meaning beyond the schema wording.

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 ('Tests TCP reachability: opens one TCP connection') and explicitly disambiguates from ICMP. It names four siblings (nslookup, trace-path, curl) with the condition selecting each, so an agent can route without opening schemas.

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

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

Explicit when-to-use routing ('For DNS only use network/nslookup, for the hop path network/trace-path, for an HTTP check network/curl') plus when-not ('This is NOT ICMP'). Covers alternatives and scope exclusions directly.

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

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

Annotations cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is covered there. The description goes further: it discloses that it runs an external binary that must be installed, sends probe packets, has no timeout parameter, and that the 30 s worker limit kills slow traces (30x3 probes can take minutes). Non-responding hops show as '* * *'. This is rich behavioral context beyond what annotations provide.

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

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

Front-loads the core operation and binary distinction, then layers in caveats and routing to siblings. Every sentence adds distinct value; no fluff. Efficient for the amount of information conveyed.

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

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

Covers the things an agent needs to call this correctly that aren't in the schema: external dependency requirement, probe-packet behavior, no timeout, worker limit, and the * * * output convention. Routing to ping/nslookup completes the picture. Nothing material is missing.

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

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

Schema coverage is 100%, so the schema documents both parameters. The description reiterates host semantics and the max_hops default/cap, but adds only the worker-limit context, which is already implied in the schema description. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('traces the network path to a host') and distinguishes itself from the similarly-named tracepath by naming the exact external binary used. Sibling differentiation is explicit via 'Use network/ping first... network/nslookup for DNS problems.'

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

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

Explicit routing: 'Use network/ping first for basic reachability, network/nslookup for DNS problems.' Also gives concrete guidance on when to lower max_hops and why. This is exactly the when/when-not/alternatives structure.

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 destructiveHint/not-idempotent, and the description goes well beyond them: it states the signal is fire-and-forget with no exit verification, documents failure modes ('no such process', 'not permitted'), refusal of PID 1 and mcpd, the privileged-grant requirement, and that output_format is ignored. This is unusually rich behavioural 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?

Front-loaded with the core action and default, then constraints and alternatives. It is dense and long for a single-signal tool, but nearly every sentence adds a distinct operational fact, so little is wasted.

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

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

Despite the absence of an output schema, the description specifies the exact return line ('Successfully sent signal SIGTERM to process N') and notes output_format has no effect. Combined with the error and permission notes, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuinely new constraint information: numbers are rejected as signal values, the SIG prefix is optional and case-insensitive, and privileged requires a grant from mcp-sudo.yaml. Only minor duplication of enum values keeps it from a 5.

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

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

The description names the exact operation (send ONE signal to ONE process by PID via kill(2)), its default behaviour (SIGTERM), and explicitly distinguishes itself from siblings like processes/list, processes/top, services/manage and docker/manage. An agent can identify this tool's role without ambiguity.

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

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

It gives explicit when-to-use guidance ('Find the PID first with processes/list or processes/top') and when-not-to-use alternatives ('To stop a managed service use services/manage ... for a container docker/manage'), including the reason (systemd may restart a killed one). Routing is fully specified.

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 safety profile (readOnly, idempotent, non-destructive); the description goes well beyond that by disclosing that cpu sorting samples for ~0.5 s and only then emits cpu_percent, that limit is applied after sorting, that kernel threads render as [name], that cmdlines can leak secrets, and how output_format changes the shape. These are non-obvious behavioral traits an agent cannot infer elsewhere.

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

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

Information-dense and front-loaded with the core purpose and result fields before branching into alternatives and behavior. The paragraph is long but nearly every clause carries new constraints; only marginal tightening is possible.

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

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

With no output schema, the description compensates by naming the JSON array fields, noting the text-table default, and explaining sort/limit interaction and the conditional cpu_percent column. Nothing an agent needs to invoke or interpret results is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: sort_by semantics (RSS largest-first, cpu costs 0.5 s), limit-after-sorting ordering, human_readable vs bytes, and the note that yaml/table/wide all collapse to JSON. That extra context lifts it above the schema baseline, though it stops short of covering every parameter.

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

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

States a specific verb and resource ('Lists processes') and enumerates the exact fields returned (PID, PPID, user, state, RSS, command), plus names the data source (/proc). It explicitly distinguishes itself from siblings (processes/top, network/connections, processes/delete, the process:// resource), so an agent can pick it without opening any schema.

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

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

Gives concrete use cases ('find a PID, filter by user or one pid, or sort by memory') and routes each alternative scenario to the correct sibling tool. This is close to an ideal when-to-use map for a crowded processes/* namespace.

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

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

Annotations already declare read-only/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the %CPU sampling window means the call blocks for roughly interval_ms (default 1000, max 10000), and %CPU is measured over that interval rather than instantaneous. It does not discuss permission requirements for privileged mode beyond what the schema says.

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

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

Front-loaded with the core behavior, then alternatives, then parameter notes. Dense but every clause carries information; the output_format sentence is long and partly mirrors the schema, which keeps it from being maximally tight.

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

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

No output schema exists, yet the description specifies the shape of/yaml output ({summary, processes}, bytes) and the wide/table layouts, so an agent knows what it will receive. All defaults and side effects an agent needs are present.

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 goes slightly beyond by restating the operative defaults (sort_by cpu, limit all, interval_ms 1000/10000) and clarifying that `user` is an exact-match username and that memory is bytes unless human_readable. Much of this duplicates the schema, keeping it below 5.

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

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

States a specific verb+resource ('Snapshot like `top -b -n 1`, read from /proc') and enumerates exactly what it returns (header fields plus process table columns). It is unmistakably distinct from processes/list and memory/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?

Explicitly routes four alternatives by task: processes/list for a lighter PID list, processes/delete to signal, memory/usage for totals, network/connections for port ownership. Conditions for choosing each are stated, not implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the 'Read-only' restatement is redundant. However the description adds real behavioral context: installed-but-never-loaded units may be missing, other unit types are excluded, and empty results return a specific message or `[]`. That goes meaningfully 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?

Purpose is front-loaded in the first sentence, followed by caveats and routing hints in a compact block. It is dense and largely earn-its-place, though slightly long with some duplication of the schema's pattern/state wording.

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

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

With no output schema, the description fully documents return behavior: per-unit text blocks plus a hint line, the exact empty-result string, and the JSON array shape with its field list. Combined with the filtering caveats, an agent has everything needed to call and interpret 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%, so the schema already documents all six parameters, including the pattern syntax and exact state values. The description restates the same pattern and state facts but adds no new syntax or defaults 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?

Opens with a specific verb and resource: 'Lists systemd .service units that systemd currently has loaded', then bounds the scope by naming what is excluded (timers, sockets, other unit types, never-loaded installed files). This lets an agent distinguish it from services/manage and timers/list without opening any schema.

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

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

Explicitly routes the agent elsewhere: 'To change a service use services/manage', the status resource for a single unit, and logs/journal-control for logs. It also gives the filtering context (loaded vs installed units). Nothing is left to inference.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), but the description adds substantial context beyond them: polkit refusals, the privileged grant requirement, job-waiting behavior with concrete completion statuses, the 30 s worker timeout, and the semantic distinction between reload and enable/disable. This is exactly the behavioral detail that annotations cannot express.

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

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

Front-loaded with the core verb set and scope before branching into prerequisites, return semantics, and sibling routing. It is dense and every clause carries information, though the run-on middle section could be split for easier scanning.

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

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

For a 3-parameter mutating tool with no output schema, the description covers the full operational picture: permission prerequisites, job-completion outcomes, timeout risk, action-specific semantics, and where to go for adjacent needs. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the enum values and the '.service' append rule are already documented in the schema itself. The description restates those semantics (reload re-reads config only if supported; enable/disable only affect boot) with little that the schema does not already provide, 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 specific verbs (starts, stops, restarts, reloads, enables, disables) against a specific resource (ONE systemd service over D-Bus). It further disambiguates scope with the '.service is appended when missing' detail, so an agent can distinguish it from services/list or process control 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 routes to alternatives by intent: services/list or the service://<name>/status resource for state, logs/journal-control for logs, docker/manage for containers, processes/delete for raw signals to a PID. It also states the normal prerequisite (privileged: true with an mcp-sudo.yaml grant) rather than leaving it to inference.

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

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

Annotations already declare read-only/idempotent behavior, and the description adds genuinely material context beyond them: the containerization caveat that /etc/os-release reflects the image rather than the host. It also discloses the resulting output shape (OS Release Info block, Kernel Info line, JSON object keys), which the annotations cannot convey.

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

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

Dense but front-loaded: purpose first, then container caveat, then output format, then sibling routing. Every sentence carries information, though the middle output-format sentence is heavy and could be tightened.

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

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

With no output schema, the description compensates by describing return content in both text and JSON modes, notes the container caveat, and points to the right siblings for adjacent data. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the accepted values' behavior and what the json object actually contains (os_release raw text, kernel line). That is useful interpretation the schema does not supply.

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

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

States a specific verb and resource ('Returns the Linux distribution and kernel version') and enumerates exactly what the data comprises (/etc/os-release contents plus the uname line). It also differentiates itself from siblings by routing CPU and kernel-parameter questions elsewhere.

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 names alternatives with the condition that selects them ('For CPU details use cpu/list, for kernel parameters kernel/system-control'), which gives clear routing. It stops just short of a full when/when-not statement for the tool itself, so 4 rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context beyond them: the unsupported rpm path, that the full list is uncapped (hundreds of entries), the installed-only filter, and exactly what the text and JSON outputs contain, including which fields are absent.

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

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

Front-loaded with the core purpose and tightly packed with only useful facts; every clause carries information. It is dense and somewhat long as a single block, but there is no filler to cut.

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

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

With no output schema, the description fully specifies the return shape for both text and JSON, notes empty-result behavior (`[]`), and covers platform limits and filtering. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning: it explains why `name` matters (unbounded result set) and gives glob/exact examples, plus clarifies that output_format json returns an array of {name, version, architecture} objects and that other format values collapse to JSON.

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 (lists installed packages) and adds the mechanism (parsing dpkg/apk package database) plus the platform boundary (rpm-based systems error out). An agent can distinguish this from system/os-release and other system tools without opening a schema.

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

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

Explicitly routes the agent: use this for installed packages, filter with `name`, and use `system/os-release` for OS/kernel version. It also states the when-not condition (rpm-based systems unsupported) and the scoping constraint (only status=installed).

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

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

Annotations already declare read-only/idempotent/non-destructive, so safety is covered; the description adds genuinely new behavioral context beyond that: unprivileged calls require the host's systemd bus, containers need `privileged: true` (which joins the host), `never` means systemd reports no trigger, and an empty result means no timer matched. This is rich disclosure that goes well past 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?

Front-loaded with purpose and the key sibling distinction, then behavior and edge cases. It is dense and lengthy, but nearly every sentence carries operational content (RFC 3339 UTC, `never` semantics, container privilege, empty-result meaning) rather than padding.

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

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

With no output schema, the description compensates by describing the returned fields (unit started, schedule, next/last run, Persistence, last result), the JSON array shape, timestamp format, and edge-case meanings. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description restates `pattern` wildcard rules, `output_format: json` returning an array, and the `privileged` container rationale, adding only slight emphasis rather than new semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Lists the systemd timers of the host') and immediately grounds it with a definition ('systemd's scheduler, the modern counterpart of cron'). It explicitly distinguishes itself from the closest sibling by noting `services/list` shows only `.service` units, so an agent can tell them apart without opening a schema.

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

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

Explicitly names the question it answers ('what runs on a schedule, and when next'), routes inspection of a started unit to `linuxctl describe system <name>` or the `service://<name>/status` resource, and states the exclusions outright ('Managing timers (start, stop, enable) is not offered by this tool'). When-to-use, alternatives, and when-not are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral context beyond that: the exact source files, that /etc/shadow is never read, and that results are sorted by uid with local-only scope. It stops short of discussing cost or auth mechanics, keeping it just below top marks.

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

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

The verb and source are front-loaded, followed by scope guardrails, output formats, and routing. Despite being a dense single paragraph, every clause carries distinct information with no filler or repetition of the annotations.

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

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

With no output schema, the description fully compensates by documenting both text and JSON return shapes and field names. Purpose, scope limits, exclusions, and alternatives are all covered, leaving nothing an agent needs to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description nevertheless adds meaning beyond the schema by showing the text output shape and naming the JSON object fields (username, uid, gid, group_name, comment, home_dir, shell, groups), and by giving a concrete min_uid example.

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 (Lists) and resource (local user accounts from /etc/passwd and /etc/group), enumerates the fields returned, and names the sibling tools (logs/logins, auth/sudo-rules) it is not. An agent can distinguish this from every sibling without opening a schema.

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

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

Gives explicit when-to-use routing ('For who logged in use logs/logins, for your own root grants auth/sudo-rules') and a clear exclusion ('LDAP/SSSD users are not listed'). min_uid's role in hiding system accounts is also stated, so selection conditions are unambiguous.

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