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

With no annotations, the description carries the full burden of behavioral disclosure. It states it reads from a YAML file and returns privileges, implying a read-only operation, but it does not mention error behavior, whether authentication is required, or what happens if the file is absent. The description is minimally transparent for a simple read operation.

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

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

The description is a single sentence, front-loaded with the key action and resource, with no filler. It earns its place entirely and is optimally concise.

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

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

For a tool with one optional parameter and no output schema, the description covers the essential behavior: what it returns and where it reads from. It lacks details like the default output format or typical use cases, but these are minor given the tool's simplicity. Overall it is adequately complete.

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

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

Schema description coverage is 100% – the output_format parameter is fully described in the schema. The description adds no additional parameter context beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it returns authorized tools and privileges from mcp-sudo.yaml. The verb 'Returns' and the specific resource make the function unambiguous, and the source file adds precision. It is distinct from all sibling tools which cover files, disks, network, etc.

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

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

No explicit guidance on when to use this tool versus alternatives, but the domain is unique among siblings (auth vs. system/file/network operations), so usage is implied. However, there is no mention of when it would be inappropriate or any prerequisites, leaving some inference to the agent.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Retrieves' implies a read-only operation, but it does not explicitly address side effects, privilege requirements, or output behavior. For a simple query tool this is a moderate gap.

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

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

The description is two short sentences with zero filler. The core purpose is front-loaded, and the second sentence adds a useful routing hint without redundancy.

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

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

With no output schema, the description still tells an agent what kind of data will be returned (CPU topology/architecture) and how it differs from load-average. The schema covers both optional parameters, so an agent can invoke the tool correctly without additional 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 description coverage is 100%, so both parameters are already documented. The description adds no extra meaning about output_format or topology_only, which is acceptable because the schema covers them fully.

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

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

The description states 'Retrieves CPU topology and architecture,' a specific verb and resource, and immediately distinguishes itself from the sibling cpu/load-average by noting that tool covers utilization. An agent can tell what this tool is for without inspecting 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?

It explicitly directs users to cpu/load-average when current utilization is needed, providing a clear alternative for a distinct use case. This is sufficient routing guidance for a focused CPU-info tool.

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

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

With no annotations provided, the description carries the full burden. The word 'Retrieves' signals a read-only operation and the data points are clear, but it does not disclose any potential side effects, permission requirements, or output behavior beyond the schema. This is adequate for a simple query tool but not richly transparent.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the sibling pointer to cpu/list adds routing value without unnecessary detail.

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

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

For a single-parameter read-only tool, the description covers what is retrieved and provides sibling context. There is no output schema, so a slightly deeper statement about return values or formatting would make it fully complete, but the current description is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the single output_format parameter is already fully documented by the schema. The description adds no parameter-level meaning beyond that, matching the baseline for high schema coverage.

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

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

The description states a specific verb ('Retrieves'), a specific resource ('system load averages'), and the exact data points (1m, 5m, 15m). It also distinguishes itself from the sibling cpu/list by explicitly noting that cpu/list covers hardware topology, making the tool's scope unambiguous.

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

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

The description clearly implies this tool is for load averages and points to cpu/list as the alternative for hardware topology. It provides useful context for choosing between siblings, though it does not enumerate explicit when-to-use or when-not-to-use conditions.

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

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

With no annotations, the description carries the behavioral burden, and it does a reasonable job: it states that this is a statistics/read operation and clarifies the default byte output versus human_readable output using df equivalents. It does not explicitly mention privilege implications or error behavior, but the described operation is clearly non-mutating and the schema fills in parameter-level details.

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

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

Two sentences with no filler: the core behavior and unit default come first, followed by a compact sibling pointer. Every clause contributes to selection or invocation.

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

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

For a read-only disk-statistics tool with fully documented parameters, the description plus schema is mostly complete. It gives the path-based semantics, unit behavior, and a relevant sibling pointer. The main gaps are not explaining how output_format interacts with the default text output and not addressing disks/usage, but these are minor given the schema coverage.

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. The description adds some context by explaining the human_readable/byte distinction, but it does not materially extend the parameter documentation beyond what the schema already states.

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

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

The description starts with a specific verb and resource: 'Returns disk space statistics of the filesystem holding a path,' and adds useful command analogies (df, df -h). It distinguishes the tool from disks/list by pointing there for block devices, though it does not explicitly disambiguate from the nearby sibling disks/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?

It gives one clear routing rule: use disks/list when the goal is to see all block devices. This helps an agent choose between two siblings, but it does not explain when disks/usage or other filesystem-related tools would be more appropriate, leaving some selection burden on the agent.

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

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

With no annotations provided, the description carries the full behavioral burden. It explicitly states the root requirement ('Must be run as root (privileged: true)'), which is a critical execution constraint, and discloses the output format (JSON with specific fields). The term 'Retrieves' implies read-only behavior, though it could more explicitly state that no modifications are made to the drive.

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

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

Four short sentences, each earning its place: the core action, the output contents, the mandatory root requirement, and the primary use case. The information is front-loaded, with the essential verb and object in the first sentence. No filler or redundancy.

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

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

For a two-parameter tool with no output schema, the description covers the essential bases: what the tool does, what output to expect, the required privilege mode, and when to use it. It could add an explicit statement that this is a read-only diagnostic operation, but the information provided is sufficient for an agent to understand and correctly invoke the tool.

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

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

Schema description coverage is 100%, with the schema already explaining that device is a block device name and privileged is required for SMART data. The description reinforces the privileged requirement ('Must be run as root') but adds no new details about parameter formats, constraints, or defaults beyond what the schema provides. This matches the baseline for fully-documented parameters.

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

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

The description states the specific verb 'retrieves' with the resource 'detailed SMART health data for a drive', and gives an exact equivalent (smartctl -j -a) plus a concrete list of returned data (self-assessment, temperature, wear leveling, sector errors). This clearly distinguishes it from sibling disk tools like disks/list, disks/usage, and disks/performance, which address different concerns.

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

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

The description gives a clear use context: 'Use this to diagnose failing hardware.' This tells an agent when to select this tool over general disk tools. However, it does not explicitly name alternatives or list conditions where the tool should not be used, so it falls just short of full exclusion guidance.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It does that well by explaining the tree shape, nested children in JSON/YAML, exact output columns, and the privileged caveat for containerized deployments. It stops short of covering error conditions or permission failures, but for a read-only listing tool this is strong coverage.

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

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

Four sentences cover description, output structure, alternatives, and an operational caveat with no filler. The most identifying information is front-loaded and every clause earns its place.

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

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

With no output schema and no annotations, the description fully compensates by explaining what is returned, how nesting works, which columns appear, and when privileged mode matters. Nothing an agent needs to select or invoke 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 the baseline is 3, but the description adds meaning beyond the schema by specifying that JSON/YAML output nests children under 'blockdevices' and mirrors lsblk -J. This gives agents practical context for output_format that the schema alone does not provide.

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 block devices as a tree'), anchors it with 'equivalent to lsblk', and lists the exact fields returned. The description also distinguishes it from relevant siblings by naming disks/free and disks/usage for other concerns.

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 agents to disks/free for free space/inode checks and disks/usage for folder size checks, clearly marking what this tool is not for. The containerized privileged hint also prescribes a concrete condition for correct host-level results.

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

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

No annotations are provided, so the description carries the burden. It conveys that the operation is read-only ('Lists') and hints at output content via the mount/findmnt analogy, but it doesn't disclose whether privileged mode is needed to see all mounts or what happens without it. This is a gap, though not a severe one for a listing tool.

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

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

Two sentences, zero fluff. The purpose is front-loaded and the alternative is stated immediately after, making it highly scannable for an agent.

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

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

For a simple, optional-parameter listing tool with no output schema, the description covers purpose, differentiation, and even an equivalent command for mental modeling. The only missing context is nuanced behavior around privileges, but the schema partially covers that. Overall, an agent can correctly invoke the tool based on this.

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 each parameter already has a clear description (e.g., fs_type, privileged, output_format). The description adds no extra parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

Description uses a specific verb ('Lists') and resource ('mounted filesystems'), and clarifies scope with the fields returned. It explicitly distinguishes itself from disks/list by directing block-device queries there, making it unambiguous for an agent choosing between siblings.

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

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

The sentence 'Use disks/list for block devices instead' provides an explicit alternative and the condition under which to switch. This is clear when-to-use guidance that an agent can act on without inference.

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

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

With no annotations, the description carries the full burden and does add useful operational context: data is parsed natively from /sys/class/block with no fdisk dependency, signaling a read-only, dependency-free operation. However, it leaves key behaviors undisclosed, such as the default scope when 'device' is omitted and behavior on an invalid or nonexistent device. This is adequate but not rich.

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

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

Two tight sentences with the core function front-loaded in the first sentence; the no-fdisk implementation note earns its place. The second sentence repeats 'partition boundaries' from the first, a minor redundancy.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers the output units (sectors and bytes) and the data source, which is most of what an agent needs. It does not state what happens when 'device' is omitted (all disks implied but unconfirmed) or for an invalid device.

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 the 'device' parameter ('Optional specific block device to query (e.g., 'sda')') and the description adds no new parameter-level detail. Per the baseline for high schema coverage, 3 is appropriate.

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

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

The description opens with a specific verb ('Retrieves') and a precise resource ('partition boundaries for a drive') with units (start/size in sectors and bytes). This scope clearly separates it from disk siblings like disks/list, disks/usage, and disks/mounts, none of which address low-level partition geometry.

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

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

The second sentence gives an explicit use case: 'Use this to understand the low-level geometry and partition boundaries of a disk.' It does not name sibling alternatives or give when-not-to-use conditions, so it falls short of full routing guidance, but the stated purpose is unambiguous context for selection.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It states the output content (read/write sectors, merged operations, wait times in ms) and the equivalence to iostat, implying read-only behavior. However, it does not disclose potential requirements (e.g., root privileges), error behavior for invalid devices, or whether it samples instantaneously or over a period, leaving some behavioral gaps.

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

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

The description is three sentences with zero fluff. The first sentence front-loads the core purpose, the second details output, and the third gives usage guidance and an alternative. Every sentence earns its place.

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

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

For a tool with only two optional parameters and no output schema, the description is fairly complete. It describes the returned metrics, the prerequisite for a valid device, and a sibling alternative. It omits edge cases like default behavior when device is omitted or error handling, but given the simplicity and the mention of iostat equivalence, it is adequate for an agent to invoke 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% with both parameters documented. The description adds value beyond the schema by linking the 'device' parameter to the prerequisite of using disks/list, and by clarifying the nature of the metrics returned. This enriches the meaning of the output_format parameter by giving context on what the output contains, exceeding the baseline.

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

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

The description clearly states the verb 'Retrieves' and the resource 'granular block device I/O performance metrics', explicitly equating it to iostat. It distinguishes itself from siblings by contrasting with disks/free for static capacity, making its purpose unmistakable.

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

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

The description provides a clear prerequisite ('Use disks/list first to find valid block devices') and identifies a specific alternative ('If you want static capacity instead, use disks/free'). It does not cover all sibling distinctions (e.g., health, usage) but gives practical routing guidance for the most common confusion.

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

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

No annotations are provided, so the description carries the full burden. It only states the calculation and gives a command analogy; it does not disclose permission requirements, the effects of the privileged parameter, default recursion behavior, or output format. For a tool with several behavior-affecting parameters, this is insufficient.

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

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

Two sentences, front-loaded with the core action and a useful analogy, then a pointer to the sibling. No fluff.

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

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

Given the complexity (11 parameters, no output schema, no annotations), the description is adequate for a basic understanding but omits important behavioral context such as privileges and recursion semantics. The sibling pointer helps, but not enough to be fully complete.

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

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

The schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds little beyond the schema—it repeats the human_readable/bytes behavior and the du analogy, but doesn't clarify other parameters like threshold or exclude. It doesn't degrade, but also doesn't compensate much.

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 ('Calculates the disk space used by a directory') and explicitly differentiates from disks/free by pointing out its use for overall partition stats. The du analogy also clarifies the exact command it mimics.

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 guidance on when to use the sibling disks/free for partition-level stats, implying this tool is for per-directory usage. It doesn't enumerate all possible alternatives, but the main confusion is resolved.

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

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

With no annotations, the description carries the full burden and does well: it discloses that symlinks are never followed, recursive operations skip and report symlinks, and numeric modes follow GNU chmod semantics with the 4-digit vs 5-digit setuid/setgid distinction. Minor vagueness remains in what 'report them' means, but the key behavioral traits 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?

Three sentences, each earning its place: the first defines the operation, the second covers the critical symlink behavior, and the third clarifies numeric mode semantics. Information is front-loaded and there is no fluff.

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

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

For a tool with no annotations and no output schema, the description covers the essential operational semantics: purpose, symlink handling, and mode interpretation. It could add what 'report them' means or clarify error behavior, but an agent has enough to invoke the 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. The description adds valuable semantic detail beyond the schema, especially the GNU chmod numeric mode behavior and the 5-digit mode example for setting setuid/setgid exactly. Other parameters like path, recursive, and privileged are already well-described 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: changes permission bits of a file or directory. The parenthetical 'chmod' and the focus on permission bits clearly distinguish it from sibling tools like files/chown (ownership) and files/update (content/settings).

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

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

The description clearly conveys when to use the tool: when permission bits need changing, including recursive application. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for an agent to select it correctly.

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

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

With no annotations provided, the description carries the full burden. It discloses the critical symlink policy (refusing paths with symlinks, skipping and reporting recursive symlinks) and the privileged requirement. This goes well beyond a bare statement of purpose and covers the most likely failure/edge cases for a chown operation.

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

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

The description is three sentences with no filler. It front-loads the core action, then states the critical symlink policy and the privilege requirement. Every sentence contributes useful information.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential operational context: purpose, privileges, and symlink handling. It does not describe return values or error handling beyond symlink reporting, but for a typical filesystem command this is sufficient to call it correctly.

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

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

The schema description coverage is 100%, so the schema already documents all parameters, including the owner format and recursive behavior. The description mostly restates the symlink behavior already present in the schema and does not add substantial new meaning to individual parameters. A baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Changes' and the resource 'file's or directory's owner and/or group', calling out 'chown' directly. This differentiates it from sibling tools like files/chmod (permissions) and files/update (content), so an agent can easily select it.

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

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

The description provides clear usage context: it warns that symbolic links are never followed and that changing the owner requires privileged: true. These are important prerequisites and behavioral constraints. It doesn't explicitly mention when to prefer this over files/chmod, but the operation is distinct enough that this is not a major gap.

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

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

With no annotations, the description carries full behavioral disclosure burden. It does disclose the key overwrite behavior ('replace file contents'), but it omits other important traits such as privileged/root writing, permission requirements, error behavior, or whether parent directories are created.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to the core meaning, making it easy to parse quickly.

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

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

For a simple three-parameter tool, the description covers the core operation adequately, and the schema fills in parameter details. However, the lack of usage differentiation from files/update and the absence of any output/response information leave meaningful gaps for an agent deciding how to invoke the tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no new parameter-level meaning beyond the word 'contents' loosely aligning with the content parameter, which is the expected baseline.

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

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

The description clearly states the action ('Create') and the resource ('file'), and adds 'or replace file contents' to cover overwriting. However, it does not explicitly distinguish itself from the sibling tool files/update, which likely also handles content replacement.

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

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

There is no guidance on when to use files/create versus files/update, and no exclusions or alternative conditions are provided. The phrase 'or replace file contents' implies an overwrite use case, but this creates ambiguity with files/update rather than resolving it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does this well by describing how the MIME type is detected (from the first bytes, natively, without file(1)) and by documenting the symlink edge case ('reported as inode/symlink, not followed'). It does not state permission requirements or lack of side effects, but for a read-only lookup these are minor omissions.

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

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

Two tightly written sentences with no filler. The core purpose is front-loaded, followed by a valuable behavioral caveat, and then a useful pointer to an alternative. Every clause earns its place.

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

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

For a simple MIME-type tool with no output schema, the description is nearly complete: it explains the operation, the symlink behavior, and how it differs from the stat alternative. It does not describe the exact return format or error behavior, but the `file -b --mime-type` analogy sufficiently implies a MIME-type string output. Minor gaps keep it from a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little parameter-specific meaning beyond the schema: it clarifies that the path is to a file and mentions symlink behavior, but does not elaborate on `privileged`. The schema already documents 'path' and 'privileged' adequately, so no penalty or bonus is warranted.

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

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

The description uses a specific verb and resource: 'Determines a file's MIME type'. It further distinguishes itself from the file/stat sibling by explicitly stating that stat is for size/permissions/ownership. The analogy to `file -b --mime-type` makes the purpose instantly recognizable.

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

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

The description gives clear routing guidance: 'Use files/stat for size/permissions/ownership instead.' This explicitly states an alternative and the condition under which that alternative should be chosen, so an agent knows exactly when to select this tool over the most likely sibling.

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

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

With no annotations, the description must disclose behavioral traits, but it only states 'Search for files' without explaining recursion, default path, permission requirements, or return format. It does not mention that the search is recursive or that it can search as root (privileged parameter). The description is essentially a bare statement of the tool's core action, lacking behavioral context.

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

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

The description is one short sentence, which is concise and not bloated. However, it is so minimal that it lacks structure and fails to front-load critical information like the fact that it searches recursively or the available filters. It is appropriately sized for a very simple tool, but for a tool with 9 parameters it is under-specified.

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?

This is a complex tool with 9 parameters, no annotations, and no output schema. The description does not mention the output format, the meaning of parameters beyond the schema, or any usage context. It is completely inadequate for an agent to understand how to effectively use the tool, such as knowing that 'path' defaults to '/' or that 'privileged' requires special permissions.

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

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

The schema descriptions cover 100% of parameters, each with a clear explanation (e.g., name, size, type). The tool description adds no additional parameter semantics; it does not explain how parameters interact or provide examples. Per the rubric, with high schema coverage, baseline is 3, and the description does not compensate or add value beyond the schema.

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

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

The description 'Search for files in a directory hierarchy' clearly states the action (search) and resource (files) with a specific scope (directory hierarchy). It is distinct from sibling tools like files/list (which lists contents) and files/read (which reads a file), though it doesn't explicitly name those alternatives. The verb and resource are specific enough to convey the purpose.

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

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

There is no guidance on when to use this tool versus files/list or other alternatives. The description does not mention that this tool is for recursive search or that it supports filters like size or mtime. No context is provided for typical use cases or exclusions.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose the key trait that symlinks are shown but never followed, and it details what the listing includes. However, it does not explicitly state that the operation is read-only or mention any side effects, permissions, or error behavior. This is a moderate gap for a listing tool, so a 3 is appropriate.

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

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

The description is a single, efficient sentence that front-loads the core purpose and then adds a precise behavioral caveat. There is no filler or redundancy, and every word contributes to understanding the 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?

Despite having no output schema, the description hints at the return content by listing the fields shown (type, permissions, size, etc.), giving the agent a good idea of the output. It does not mention output format explicitly, but that is covered by the output_format parameter. Given the tool's simplicity and the rich parameter schema, this is largely complete, though it could note read-only nature for full transparency.

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

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

Schema coverage is 100%, so all parameters are already documented. The description adds marginal value by referencing ls -la, which implies the default long format, but it does not elaborate on any specific parameter beyond the schema. Per the calibration, a baseline of 3 is correct when the schema handles parameter documentation.

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

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

The description clearly states the verb ('Lists') and resource ('a directory'), and enriches it with the ls -la analogy and specific details (file type, permissions, symlink targets). This makes its purpose unambiguous and distinguishes it from siblings like files/read (content reading) and files/find (search).

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

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

The description gives clear context that this tool lists directory contents, which is enough for most cases. It does not explicitly mention when not to use it or name alternatives, but the purpose is so straightforward that the lack of exclusions is acceptable. A 4 reflects the clear context without explicit alternative routing.

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

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

No annotations are provided, so the description carries the full burden. It discloses chunking/streaming support and the ability to read as root (via the privileged parameter), which adds behavioral context. However, it doesn't mention what happens with large files, encoding, or error cases, and the 'precision reading' phrasing is vague.

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

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

The description is a single sentence that is concise and front-loads the core purpose ('Precision reading of file contents'). The chunking/streaming detail is useful and earns its place, though 'precision' is somewhat filler.

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

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

For a read tool with six parameters and no output schema, the description is adequate but not complete. It doesn't explain return format, pagination behavior, or how line-based and byte-based reads interact. The schema covers parameter semantics, but the description could add more context about expected output and edge cases.

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 six parameters. The description adds the concept of chunking/streaming, which hints at how limit/offset/start_line/end_line work together, but it doesn't explain precedence or interaction beyond what the schema states. Baseline 3 is appropriate.

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

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

The description states a specific verb ('reading') and resource ('file contents'), and mentions chunking/streaming support, which distinguishes it from sibling tools like files/list or files/find. However, it doesn't explicitly name a sibling alternative or contrast itself with other file tools, so it falls short of full differentiation.

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

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

The description implies usage for reading file contents with chunking/streaming, but provides no explicit guidance on when to use this tool versus alternatives like files/list, files/find, or files/filetype. The context is clear enough for a read operation, but no exclusions or alternative routing are stated.

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

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

Annotations are absent, so the description carries the behavioral burden. It does disclose the two mutating behaviors (append vs range replacement), but it leaves out side effects, permission requirements despite the 'privileged' parameter, and behavior for missing files or invalid ranges.

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

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

One front-loaded sentence states the core action first and then the two supported modes. Every phrase contributes; 'programmatically' is slightly redundant but not harmful.

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

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

For a 6-parameter mutation tool with no annotations or output schema, the description is reasonably complete at a high level, and full parameter descriptions fill in details. However, it does not clarify whether append and line-range replacement are mutually exclusive or what the default behavior is when no range is provided, leaving clear gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a high-level mapping of append to append mode and start_line/end_line to range replacement, but it does not explain parameter combinations or required relationships, so it stays at baseline.

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

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

The description uses a specific verb ('edit'), names the resource ('a file'), and differentiates the operation by listing two concrete modes: appending text and replacing line ranges. This clearly separates it from siblings like files/create, files/read, or files/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?

The usage context is implied rather than explicit: editing existing files belongs here, while creating new files belongs elsewhere. However, no alternatives are named and no when-not-to-use guidance is provided, so an agent must infer the tool's place among siblings.

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

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

No annotations are provided, so the description must carry the burden. It discloses that writes mutate state, require privileged=true, and can be restricted per user via mcp-sudo.yaml. It does not detail output/error behavior, but covers the main permission and safety context.

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

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

Two tight sentences with no filler. The action and mechanism are front-loaded, followed by the critical permission/restriction context. Every sentence 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?

Coupled with the fully-documented schema, the description covers the operation, runtime nature, privileged write requirement, and per-user restrictions. It lacks output/error details and persistence notes, but for this tool the coverage is nearly complete.

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

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

The input schema already provides detailed descriptions for all 4 parameters, including dotted/slash forms, directory subtree reads, value-omitted reads, and read_all semantics. The description adds no new parameter-specific meaning beyond restating the privileged requirement.

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 (reads/writes), a clear resource (kernel parameters, sysctl equivalent), and the mechanism (/proc/sys). This clearly distinguishes it from sibling tools like system/os-release or network/connections.

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?

Clearly conveys that it is for accessing kernel parameters at runtime, and that writes require privileged=true. It does not explicitly name alternatives or exclusion conditions, but the context is sufficiently clear.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the kernel ring buffer and its purpose for hardware/driver logs, which is helpful context, but it does not disclose details such as whether the buffer is cleared after reading, whether the tool requires privileges (though there is a 'privileged' parameter implying that), or how much data is returned. The description adds some behavioral context but falls short of fully disclosing the tool's internal 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?

The description is a single sentence with no unnecessary words. It front-loads the core purpose and is highly efficient. Every word earns its place.

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

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

Given the tool's moderate complexity (3 parameters, none required, no output schema), the description is somewhat brief. It explains the tool's primary purpose but lacks details on return format, potential side effects, or parameter usage specifics. An agent might still need to inspect the schema fully to understand how to use it correctly, but for a read-only system tool, it may be sufficient.

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 three parameters. The description does not add any additional meaning beyond what the schema provides—it does not explain the allowed values for 'level' or 'output_format', or clarify the effect of 'privileged'. Since the schema is fully descriptive, a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: reading the kernel ring buffer specifically for hardware and driver logs. The verb 'Read' specifies the action and the resource 'kernel ring buffer' is precise, distinguishing it from other log-related tools like logs/journal-control or logs/logins, which focus on different 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?

The description implies usage for hardware/driver diagnostics, but it does not explicitly state when to use this tool over alternatives like logs/journal-control or logs/logins, nor does it mention any exclusions or prerequisites. It gives a clear context (kernel ring buffer) but no guidance on when not to use it or when a sibling would be more appropriate.

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

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

With no annotations provided, the description carries the full burden of disclosure. It clearly indicates a read-only query operation, and importantly explains the privileged requirement and why it exists ('journalctl only exists on the host, never in this daemon's own image'). It does not mention output format, volume, or failure modes, but the key behavioral caveat is well covered.

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

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

Two sentences, no filler, and the most important operational caveat is placed prominently. Both sentences earn their place: one states the tool's function, the other states a critical deployment requirement.

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

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

Given the complete parameter schema and the absence of annotations, the description covers the main operational risk (privileged/host access) and clearly identifies the tool's purpose. It could add a bit more about output expectations or when to prefer sibling log tools, but for a read-only journal query it is largely sufficient.

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. The description adds some rationale for the privileged parameter, but it largely restates what the schema already says ('required in containerized deployments'). No additional semantics are provided for the other eight parameters.

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

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

The description uses a specific verb ('Queries') and clearly identifies the resource ('the systemd journal') with the helpful 'journalctl equivalent' shorthand. It does not explicitly differentiate from sibling tools such as logs/dmesg or logs/logins, so it stops short of a 5.

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

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

The description gives no guidance on when to choose this tool over alternatives like logs/dmesg or logs/logins. The only usage-related note, 'Requires privileged: true in containerized deployments', addresses an environment prerequisite rather than tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that output is raw text rather than JSON and explains why: `last`/`lastb` output isn't reliable to hand-parse. This is important behavioral context that goes beyond the schema, though it could also mention that this is a read-only operation.

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

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

The description is concise, well-structured, and front-loaded with the core purpose followed by the mode distinction and the critical raw-text warning. Every sentence contributes meaningful information without redundancy.

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

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

Given four optional parameters, high schema coverage, and no output schema, the description provides the essential extra context: raw text output and command wrapping behavior. It could add a brief note about the output format of `last`/`lastb`, but the current description is adequate for an agent to select and invoke the 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?

The input schema has 100% description coverage, so the description does not need to repeat parameter meanings. The main description adds useful context about what the `type` parameter maps to in terms of underlying commands, but this is already partially covered by the schema. This is a solid baseline performance.

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

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

The description clearly states the tool lists login history and explicitly distinguishes the two modes: successful logins via `last` and failed attempts via `lastb`. This makes the tool's purpose easy to understand and differentiates it from other log-related siblings like `logs/dmesg` and `logs/journal-control`.

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

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

The description gives clear usage context by explaining the `type` parameter and which command each mode wraps, and it warns that `failed` typically requires root privileges. It does not explicitly mention alternatives or when not to use this tool, but the scope is sufficiently clear from the description and sibling names.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Returns' implying read-only, but does not explicitly state that it has no side effects, requires no special permissions, or describe any potential limitations or output behavior beyond what the schema 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?

Two concise sentences with zero waste. The primary purpose is front-loaded, and the alternative guidance is included succinctly. Every word earns its place.

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

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

The description explains the core function and points to an alternative, but given no annotations and no output schema, it lacks explicit mention of side effects, return format details beyond parameters, or any prerequisites. It is usable but not fully comprehensive.

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

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

The schema description coverage is 100%, so the baseline is 3. The tool description adds no additional meaning to the parameters (detailed, output_format, human_readable) – they are fully documented in the schema, so no credit beyond baseline.

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

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

The description states a specific verb ('Returns') and a clear resource ('memory and swap utilization information'). It also distinguishes itself from the sibling tool cpu/load-average by explicitly pointing to it for compute load, making the purpose unambiguous.

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

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

The description explicitly instructs to 'Use cpu/load-average to check compute load,' which tells the agent when NOT to use this tool and directs to a specific alternative. This is clear guidance on usage versus siblings.

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

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

With no annotations, the description carries the full behavioral burden. 'View' conveys a read-only operation and the parenthetical hints at what is returned, but it does not mention interface-specific behavior, output format, or any required privileges. This is minimally adequate for a simple read-only tool.

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

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

A single, front-loaded sentence that states both the action and the data being shown. No wasted words or redundant details.

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

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

The core purpose and output concept are clear, and the tool can be called with zero parameters. However, the interface parameter is left unexplained and there is no output detail, leaving noticeable gaps for such a simple tool.

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

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

The schema has 0% description coverage and the description never mentions the 'interface' parameter. An agent has no way to learn whether it filters by network device, is optional, or affects the output.

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

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

The description uses a specific action ('View'), names the resource ('system ARP cache'), and clarifies the content with 'IP to MAC address mappings'. This cleanly distinguishes it from network siblings like ping or curl.

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

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

The description does not state when to prefer this tool over alternatives such as network/connections or network/ping, nor does it give any exclusion guidance. The usage context is only implied by the action itself.

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

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

With no annotations provided, the description bears the full burden of behavioral disclosure. It reveals the data source ('read natively from /proc/net (no ss needed)'), the privilege requirement ('shown only with privileged: true'), and subtle state semantics ('LISTEN includes unconnected UDP'). It stops short of describing output formatting or error behavior, but covers the essential operational traits.

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

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

The description is compact and front-loaded: purpose first, then implementation details, privilege caveat, state semantics, and a routing hint. Each sentence adds useful information. It loses one point for slight redundancy with the schema's state examples, but there is no filler.

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

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

For a 4-parameter tool with no output schema and no annotations, the description supplies the key invocation context: what is listed, how it is read, when privileges are required, and how state filtering behaves. The only meaningful omission is a concrete description of the return shape, but the agent has enough to select and call the 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. The description adds genuine meaning beyond the schema: it explains state groups ('connected/synchronized'), the LISTEN/UDP nuance, and the privileged behavior. Those details elevate parameter understanding without repeating 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?

The description names a specific resource ('TCP and UDP sockets') and a specific action ('Lists') with scope ('in every state with their owning processes'), and anchors it with the familiar `ss -tuanp` analog. The closing hint about physical links routes to network://interfaces, distinguishing it from related network tools.

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

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

The description makes the primary use case explicit: listing TCP/UDP sockets and their owning processes. It also provides a when-not and an alternative: 'For physical network links and IPs, use the network://interfaces resource.' State-group guidance ('connected/synchronized') further tells the agent how to tailor invocations.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'native HTTP client' but does not disclose important behaviors such as following redirects, handling cookies, or default method (likely GET). It does not mention authentication handling or potential side effects (e.g., making external calls), but for a data transfer tool, the description is adequate though not rich. There is no contradiction with annotations since none exist.

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

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

The description is a single concise sentence that front-loads the core purpose. There is no wasted text, and it is easily digestible for an agent. It earns its place by stating the verb and resource, though it could add more detail without becoming bloated.

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

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

Given the tool's moderate complexity (7 params, nested headers object) and no output schema, the description is somewhat thin. It does not explain return value structure (e.g., status code, truncated field), but the schema's max_body description mentions truncated: true, hinting at output. It lacks guidance on error handling or default behaviors, but for a simple HTTP client, it is minimally complete for basic calls.

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 57%, so the description should compensate for undocumented parameters. The description adds the word 'native' and 'HTTP', but does not explain key parameters like method, timeout, or max_body in detail. However, the schema has descriptions for body, headers, insecure, and max_body, which cover most params. The method param has no description, and the description does not clarify it, but the baseline is 3 and the description adds a little value, so 4 is appropriate for partial compensation.

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

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

The description states a clear verb ('Transfer') and resource ('data from a URL'), distinguishing it from sibling network tools like ping, nslookup, and trace-path, which are also network-related but serve different purposes. It is concise and unambiguous, though it does not explicitly mention that it supports multiple HTTP methods, which is implied by the presence of a method parameter.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It implies usage for HTTP requests, but does not mention exclusions (e.g., not for file transfers via SCP) or alternatives like files/read for local files. Given the sibling tools are diverse, more guidance would be helpful, but the description is not misleading.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Query' indicates a read-only operation and 'natively' hints at system-level DNS resolution, but the description does not disclose default record_type behavior, return format, timeout behavior, or potential failure modes.

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

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

The description is very short and front-loaded with no filler words. However, it is under-specified for a tool with two parameters and no additional annotations, so the brevity is not fully appropriate.

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

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

For a network tool with no annotations and no output schema, the description is incomplete. It does not explain the default record type, what the returned data looks like, or how this tool differs from sibling network tools.

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

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

Schema description coverage is only 50%, and host has no description in the schema. The description does not mention either parameter or compensate for the missing host semantics; the only parameter guidance comes from record_type's inline example list.

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

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

The description uses a specific verb and resource: 'Query DNS records' clearly identifies what the tool does. It conveys more than just the tool name, though it does not explicitly contrast with sibling network tools like curl or connections.

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

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

There is no guidance about when to use this tool versus alternatives such as network/curl or network/ping. The context of DNS records gives some implicit signal, but no explicit when-to-use or when-not-to-use guidance is provided.

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

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

With no annotations, the description carries the full behavioral burden, but it only states the metric being measured and the protocol. It does not disclose whether the tool performs a TCP handshake, what output or exit status it returns, whether elevated privileges are needed, or how timeouts and errors are handled.

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

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

A single, front-loaded sentence with no filler or repetition. It communicates the core operation immediately and earns its place.

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

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

For a tool with three parameters, no annotations, and no output schema, a one-line purpose statement is not enough. Missing context includes expected output, port/timeout behavior, error cases, and permission requirements, so an agent would have to inspect the schema or guess to invoke this correctly.

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

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

Schema coverage is only 33%, so the description needed to compensate for port and timeout semantics, but it does not. It names the host as the target, yet says nothing about the port defaulting to 80, the meaning of timeout, or how these parameters affect the measurement.

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

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

The description uses a specific verb ('Measure') and a precise resource ('TCP reachability and latency to a host'), which clearly distinguishes this from sibling network tools like network/curl (data transfer), network/nslookup (DNS resolution), and network/trace-path (route tracing). It also clarifies that this is a TCP-level probe, not a generic ICMP ping.

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

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

The wording implies the tool is for reachability/latency diagnostics, so an agent could infer when to use it. However, it gives no explicit when-to-use or when-not-to-use guidance, and it does not name alternatives such as curl or trace-path for cases where transferring data or tracing routes is needed.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It conveys that this is a read-only traceroute-style operation and mentions latency measurement, but it does not describe output format, packet protocol, or privilege requirements. Adequate but with gaps.

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

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

Two sentences plus a hint, front-loaded with the core definition and no filler. Every sentence adds value: definition, use cases, and a practical alternative.

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

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

For a simple two-parameter read-only diagnostic, the description covers what the tool does and when to use it, and the traceroute analogy implies the output shape. It lacks explicit output/return details in the absence of an output schema, but the use cases and hint make it reasonably complete.

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

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

Schema covers both parameters with descriptions (host, max_hops), so the baseline is 3. The description adds no parameter-specific detail beyond the schema, but none is needed given the full schema coverage.

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 ('Traces') and resource ('network path to a host') and anchors the meaning with 'equivalent to traceroute'. This clearly differentiates it from sibling network tools like ping and nslookup.

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 lists diagnostic use cases (routing issues, dropped packets, latency) and directs agents to use network/ping for basic reachability first, implying trace-path is for deeper investigation. This is clear when-to-use and alternative guidance.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It only states that a process is terminated, but does not mention that this is irreversible, what signal is sent by default, whether root privileges are required for other users' processes, or potential side effects on child processes.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the core action efficiently and is appropriately sized for the tool's simplicity.

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 operation with no annotations and no output schema, this description is too thin. It omits crucial operational details such as signal default behavior, permission requirements, and what the response will contain, leaving an agent under-informed for a high-impact call.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds only that the PID identifies the target, which slightly reinforces the required parameter but provides no extra meaning for signal, privileged, or 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?

The description states a specific verb ('Terminates') and resource ('a specific process by PID'), making the tool's action unambiguous. It is clearly distinct from process listing tools like processes/list and processes/top.

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

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

No guidance is given on when to use this tool versus alternatives, nor are any caveats or exclusions mentioned. An agent is not told how this relates to process listing or service management, so it must infer appropriate use from the name alone.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It states it lists processes, implying a read-only action, but does not explicitly mention whether it requires privileges, how it handles the 'privileged' parameter, or any potential side effects. The description is minimal but not misleading.

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

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

Two concise sentences with no redundancy. The key action (list processes, find PID) is front-loaded, and the follow-up resources are mentioned briefly. Every word serves a purpose.

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

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

The tool is a simple list operation with clear schema definitions for all parameters. The description provides the essential workflow (find PID, then act). Since there is no output schema, it doesn't describe return format, but for a list tool that's an expected gap. It adequately covers the core use case.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description itself adds little beyond the schema—only the hint that it's for finding a PID, which is a context for the 'pid' parameter but not a deep semantic addition.

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

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

The description clearly states the verb ('Lists') and the resource ('running processes on the system'), and immediately distinguishes its purpose from siblings like processes/top and processes/delete by stating its use ('to find a PID'). No ambiguity about what the tool does.

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

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

It explicitly ties usage to a workflow: 'Use this to find a PID', and then directs to process://{pid}/{target} or processes/delete for next steps. It doesn't mention when to use alternatives like processes/top, but it provides clear situational guidance for its primary role.

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

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

With no annotations, the description carries full behavioral disclosure. It clearly states this is a non-continuous snapshot, discloses that %CPU is measured over a short sampling interval, explains memory unit behavior with human_readable, and lays out the full output structure including header fields and process columns. This gives an agent an accurate model of invocation outcomes without hidden 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?

The description is front-loaded with a concrete analogy ('top -b -n 1') and then packs only high-value details: exact columns, units, sampling behavior, and sibling routing. Every sentence earns its place, and there is no filler or repetition of schema boilerplate.

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

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

Given the absence of an output schema, the description compensates thoroughly by enumerating the snapshot header, process table columns, memory units, and %CPU sampling semantics. Combined with the schema's rich parameter descriptions, an agent has everything needed to call the tool and interpret its output 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 schema already documents all seven parameters in detail; the description adds little beyond reinforcing the human_readable unit behavior and sampling context. It does not materially extend parameter understanding beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description defines the tool as 'A snapshot like `top -b -n 1`' with a specific verb (snapshot) and resource (processes), and enumerates the exact header and table columns. It explicitly distinguishes itself from siblings by pointing to processes/list and processes/delete, so an agent can clearly identify what this tool uniquely does.

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 direct routing guidance: 'Use processes/list for a plain listing, processes/delete to signal a process.' This explicitly names alternatives and the conditions for choosing them, plus the header/process-table details signal when a top-style snapshot is appropriate.

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

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

With no annotations, the description carries the behavioral burden. It discloses the output fields, which is useful, and the verb 'Lists' implies a read-only operation, but it does not explicitly state that no services are modified or that privileged execution may be required.

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

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

Two short sentences with no filler: the first states the purpose and the second names the key output fields. The structure is compact and front-loaded.

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

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

The schema fully documents parameters, and the description names the main output fields, making this adequate for a simple list tool. However, there is no output schema, no annotations, and no guidance about privileges or the relationship to services/manage, leaving some gaps.

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

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

All six parameters have descriptions in the schema, so schema coverage is 100%. The description adds no parameter-specific meaning beyond the general 'optional filtering' phrase, which matches the baseline for high schema coverage.

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

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

The description opens with 'Lists systemd services', giving a clear verb and resource, and notes optional filtering. It does not explicitly contrast with the sibling services/manage tool, so it stops just short of full sibling differentiation.

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

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

The description gives no guidance on when to choose this tool over services/manage or other alternatives, and mentions no prerequisites. 'With optional filtering' hints at invocation style, not decision 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?

No annotations are provided, so the description carries the full burden of disclosing behavior. It states that it controls services and lists actions, but it does not disclose that these actions mutate system state, may require root privileges, can disrupt running workloads, or that enable/disable affects persistent configuration. The schema's privileged parameter hints at root requirements, but the description itself provides no such context.

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

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

The description is three short sentences with the core purpose front-loaded and every sentence earning its place. It contains no filler, boilerplate, or redundant restatement of 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?

Given the simple three-parameter schema and full schema coverage, the description is largely complete: it defines the tool's function and points to the right alternatives for status and logs. The main gap is the lack of behavioral context around privilege requirements and side effects, but the schema's privileged parameter and the self-explanatory action enum compensate enough to keep this above average.

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

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

Schema description coverage is 100%, so the parameters are already fully documented by the input schema. The description lists most actions but adds no additional meaning beyond the schema and actually omits 'reload', which is present in the enum. Per the baseline rule for full schema coverage, a 3 is appropriate.

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

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

The description opens with the specific verb 'Control' tied to systemd services and enumerates the exact operations (start, stop, restart, enable, disable), making it immediately clear that this is a mutation tool for service state. It also distinguishes itself from sibling tools like logs/journal-control by naming the alternatives for logs and status. This is a precise, resource- and verb-scoped definition.

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

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

The description explicitly routes the agent away from this tool for two adjacent use cases: detailed service status should go to the service://{name}/status resource, and logs should go to logs/journal-control. This gives clear when-to-use and when-not-to-use guidance for the most likely confusable alternatives. The control purpose itself is self-evident from the action list.

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

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

With no annotations, the description carries the burden of disclosing behavior. 'Retrieves' implies a read-only operation, but the description does not mention output shape, default format, or potential errors. The output_format parameter is absent from the description, adding a small transparency gap.

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

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

The description is a single, front-loaded sentence with no filler. Every word carries meaning, making it highly efficient.

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

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

For a simple informational tool with no output schema and no annotations, the description is largely sufficient: it says what is retrieved, and the parameter schema covers the configurable option. It lacks explicit read-only confirmation and output-format details beyond the schema, but nothing critical is missing for correct invocation.

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

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

The schema provides 100% coverage for the single parameter, including examples and a default value. The description adds no additional parameter context, but the high schema coverage sets the baseline at 3.

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

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

The description states a specific verb and resource ('Retrieves Linux distribution and kernel version') and directly matches the tool name. It is clearly distinct from sibling tools like kernel/system-control or system/packages, which address different concerns.

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

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

No guidance is given about when to use this tool versus alternatives, nor any exclusions or prerequisites. With many sibling system-information tools, the agent must infer usage solely from the name and short description.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses auto-detection and the rpm limitation, but it does not state whether the operation is read-only, whether root privileges are ever required, or what the output structure looks like. For a read-oriented list tool, this is partially transparent but leaves important behavior unspecified.

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

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

The description is a single, information-dense sentence. It front-loads the primary action ('Lists installed packages'), then adds auto-detection and the rpm caveat. Every clause earns its place; there is no fluff 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?

With no output schema, the description should compensate by explaining what the tool returns or any side effects. It does neither. It also doesn't clarify when the privileged parameter might be needed or whether the operation is safe to run. The tool is simple, but an agent would need more context about output format and potential permission requirements to 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?

The input schema has 100% parameter description coverage, so each parameter is already documented. The tool description adds no additional meaning beyond the schema, such as parameter interactions or default behaviors. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool lists installed packages and specifies the package manager auto-detection. It also explicitly notes rpm-based systems are unsupported, distinguishing it from potential alternatives like system/os-release. The verb-resource pair is specific and unambiguous.

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

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

The description provides clear context on when to use this tool (listing packages) and highlights a key limitation (rpm not supported). It does not explicitly name alternative tools or state when not to use it, but the limitation effectively guides an agent away from rpm environments. This is above average but not a full 5 since no explicit exclusions or alternatives are mentioned.

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

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

With no annotations, the description carries the full burden. It discloses a safety-critical behavioral trait: it never reads /etc/shadow and therefore does not expose credentials. It also states the data source and covered fields. Minor gaps remain, such as ordering, default filtering behavior, and root/permission behavior, but the key security boundary is clearly 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?

Two compact sentences with no filler. The core function is front-loaded, and the '/etc/shadow' disclaimer earns its place as a critical behavioral boundary. Every sentence adds value.

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

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

For a simple, optional-parameter tool with no output schema, the description conveys source, output content, and security scope well. It does not specify the default output format or default min_uid behavior, but those are covered by the parameter schema and are not critical gaps.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no parameter-specific semantics beyond the fields listed, and with full schema coverage the baseline of 3 is appropriate.

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

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

Uses a specific verb ('Lists'), names the exact resource ('/etc/passwd'), and enumerates the returned fields (uid, gid, home, shell, group memberships). The phrase 'account identity, not credentials' further disambiguates the tool's scope and prevents confusion with a credential-reading tool.

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

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

Provides clear context on when to use this tool: when account identity is needed, explicitly stating it never reads /etc/shadow and reports identity rather than credentials. It does not name alternative tools or give explicit when-not-to-use conditions, so it stops short of a full 5.

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