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

With no annotations present, the description carries the full burden and does so: it declares read-only behavior, that it takes no arguments, and that it re-reads from disk on every call so results reflect drift since server start rather than cached state. That freshness guarantee is exactly the kind of behavioral trait structured fields cannot convey.

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

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

Two sentences, front-loaded with the validation scope, followed by the freshness guarantee and read-only statement. Every clause adds distinct information with no repetition of the name or schema.

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

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

For a zero-argument, read-only validation tool with an output schema covering return values, the description supplies everything an agent needs: what is validated, that it is safe to call freely, and why the result may differ from loaded state. Nothing material is missing.

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

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

There are zero parameters, so the baseline is 4. The description confirms 'takes no arguments', which is consistent with the empty schema and removes any ambiguity about hidden inputs.

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

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

States a specific verb (validate) and resource (the inventory file), then enumerates exactly what is checked: parse/structural validation, ${VAR} environment variables being set, and SSH key/kubeconfig file existence and readability. This is clearly distinguishable from siblings like cisco_inventory or list_servers, which list rather than validate.

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

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

Gives clear context for use — validating the inventory file's on-disk state — and the drift note tells the agent when this result is more trustworthy than in-memory state. It stops short of naming an alternative tool or an explicit 'use this before doing X' rule, so it is clear context without exclusions.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that Telnet sessions auto-send 'terminal length 0', that SSH sessions do not because each command runs in an ephemeral session, and that SSH pagination can silently truncate output to the first page. It omits auth requirements and does not restate the read-only nature, but the pagination/transport behavior is genuinely valuable context beyond the schema.

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

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

Purpose is front-loaded in the first clause, with transport caveats following. The nested em-dash parenthetical is dense but each clause earns its place by preventing a wrong conclusion about output completeness.

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

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

An output schema exists, so return-value explanation is not required, and the description supplies the one non-obvious operational risk (SSH truncation). For a single-parameter fetch tool this is close to complete; only credential/prerequisite context is absent.

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

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

Only one parameter exists and schema description coverage is 100% ('the inventory router/switch name'), so the schema already does the work. The description adds no syntax, naming convention, or validation detail about the device argument. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch a Cisco device's running configuration') and even names the underlying command ('show running-config') plus the 'as-is' scope. It does not, however, distinguish itself from the sibling cisco_backup_diff, which is the obvious adjacent tool an agent might confuse it with.

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

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

The description explains condition-dependent behavior (Telnet vs SSH) and a truncation caveat, which implies when the output will be complete. But it never states when to choose this tool over cisco_backup_diff or any other sibling, and gives no prerequisites such as credential or reachability requirements.

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

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

With no annotations, the description carries the full burden and does disclose the non-obvious stateful behavior — that the tool persists snapshots per device and behaves differently on first vs. subsequent calls. It omits auth requirements and rate/return details, but the baseline/diff disclosure is genuinely valuable.

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 action front-loaded and the baseline caveat following. No filler; 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?

An output schema exists, so return structure needn't be described. Between the schema (param) and the description (stateful behavior and drift semantics), an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the single 'device' parameter is already documented as the inventory router/switch name. The phrase 'for the same device' reinforces that identity matters, but adds no new syntax or format meaning. Baseline 3 applies.

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

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

States specific verbs (Fetch, diff) and resources (Cisco running configuration vs. last snapshot), plus the outcome ('flags unexpected config drift'). An agent can distinguish this from cisco_backup or cisco_interfaces without opening the schema.

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

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

Explains the stateful call sequence clearly: the first call establishes a baseline, later calls diff against it. That is strong contextual guidance, but it never names when to prefer it over the sibling cisco_backup, so it stops short of 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 behavioral burden. The verb 'List' implies a non-destructive read and the CLI equivalent ('show ip interface brief') reinforces that, but nothing is said about device reachability, authentication requirements, or timeout behavior. It adds some value via the CLI mapping yet leaves operational caveats undisclosed.

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

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

A single sentence that front-loads the action and resource and appends the exact CLI command as a clarifying anchor. No filler and nothing redundant.

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

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

An output schema exists, so return values need not be described, and the single parameter is documented in the schema. The remaining gap is the absence of any behavioral context (device reachability, auth, errors) for a tool with zero annotations, but for a simple read-only listing this 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?

There is a single parameter ('device') with 100% schema description coverage ('the inventory router/switch name'), so the schema already does the heavy lifting. The description adds no further detail such as naming format or whether the name must match cisco_inventory entries.

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

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

The description states a specific verb and resource ('List a Cisco device's interfaces') and enumerates the returned attributes (IP address, admin/link status, line protocol state), which makes the tool's intent unambiguous. It does not explicitly differentiate itself from siblings like cisco_version or cisco_inventory, but the interface-listing scope is obvious enough to route correctly.

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

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

Usage is only implied: an agent can infer this is the tool for inspecting interface state on a Cisco device. There is no explicit guidance on when to prefer it over cisco_logs, cisco_version, or a generic run_command alternative, nor any stated prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only listing and discloses the shape of the data (component type plus PID/VID/serial), but says nothing about permissions, device-unreachable behavior, or whether it can be slow — reasonable gaps for a simple read, but not rich disclosure.

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

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

A single front-loaded sentence: verb, resource, component examples, returned identifiers, and the underlying command. No filler and nothing buried.

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

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

For a one-parameter read tool with an output schema (so return values need no explanation), the description covers purpose, scope, and output fields adequately. Only the lack of explicit routing guidance against cisco_version/cisco_interfaces keeps it short of complete.

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

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

One parameter with 100% schema description coverage ('the inventory router/switch name'), so the schema already does the work. The description adds only that the device is a Cisco device whose hardware is enumerated; no format or naming-convention detail beyond the schema. Baseline 3 per coverage rule.

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

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

States a specific verb (List) and resource (hardware components) with concrete examples — chassis, modules, PSUs — and explicitly names the fields returned (PID/VID/serial number). The parenthetical 'show inventory' anchors it against siblings like cisco_interfaces, cisco_version, and cisco_logs at a glance.

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

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

Usage is implied by the domain command it mimics, but there is no explicit when-to-use or when-not guidance, and no sibling is named as an alternative. An agent can infer this is the hardware-inventory read versus a software-version or interface read, but must infer it.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the messages come from the device's *buffered* log (not a live stream) and that `limit` returns the most recent lines in original order. It says nothing about permissions/credentials needed, buffer rotation, or output size — real gaps, though the operation is implicitly a safe read.

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

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

A single tight sentence that front-loads the action and resource, then adds the optional cap. Every clause earns its place and nothing is padded.

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

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

For a simple two-parameter read tool with an output schema present, the description need not explain return values and covers the core semantics. Only the absence of any access/prerequisite context keeps it from being fully complete.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the ordering behavior and the default of all buffered lines. The description restates the `limit` semantics without adding format or unit details beyond the schema, so baseline 3 applies.

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

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

The description names a specific verb ("Fetch") and resource ("a Cisco device's buffered syslog messages") and anchors it to the underlying CLI command ("show logging"). The device scope implicitly separates it from docker_logs/kubectl_logs, but it never explicitly routes against those siblings.

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

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

There is no statement of when to use this tool versus alternatives (e.g. kubectl_logs, docker_logs, journal_errors) or any prerequisite context. Usage is only inferable from the resource name; no exclusions or conditions are given.

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

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

No annotations are provided, so the description carries the full burden. 'Get' and the 'show version' reference imply a safe read operation and the description discloses what is returned (version, hostname, uptime), but it says nothing about required credentials, target reachability, or failure behavior.

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

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

A single sentence that front-loads the verb and resource and appends the exact CLI command as a clarifying cue. Nothing is wasted or buried.

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

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

Output schema exists, so return values needn't be explained, and the description still names them helpfully. For a one-parameter read tool this is essentially complete; only the absence of any usage or behavioral context keeps it from a 5.

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

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

Schema description coverage is 100% – the single 'device' parameter is fully documented in the schema as the inventory router/switch name. The description adds no additional meaning about the parameter, so the baseline 3 applies.

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

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

Specific verb 'Get' plus resource 'Cisco device's software version, hostname, and uptime', even quoting the underlying 'show version' command. It's clear what the tool returns, though it doesn't explicitly distinguish itself from siblings like cisco_inventory, uptime, or kernel_version.

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

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

No when-to-use or when-not-to-use guidance, and no mention of alternatives such as cisco_interfaces or cisco_inventory that overlap on Cisco device introspection. Usage is only implied by the resource name.

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

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

No annotations, so the description carries the full burden. It does add real behavioral detail the schema lacks: the metric is aggregate (not per-core) and sampled over a 1-second window, and it returns a severity and recommendation. However it is silent on access requirements, behavior when the server is unreachable, and whether repeat polling is safe.

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

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

A single dense sentence, front-loaded with the verb and resource, with sampling scope and output characteristics appended. No filler and nothing repeated from 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?

An output schema exists, so return contents need not be explained; the description correctly focuses on sampling semantics. For a one-parameter read tool this is nearly sufficient, with only the missing usage/alternative guidance keeping 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% for the single 'server' parameter ('the inventory server name to check'), so the schema already does the work. The description adds no format or source-of-truth detail beyond it; baseline 3 applies for a 1-param tool with 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?

Specific verb+resource: 'Report aggregate CPU utilization on a Linux server,' with the 1-second sampling window and severity/recommendation output named. An agent can distinguish it from disk_usage or memory_usage by resource, though the description never explicitly contrasts with those siblings.

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

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

Usage is implied (performance triage of a Linux host) but there is no explicit when-to-use instruction, no exclusions, and no routing to alternatives like running_processes or uptime. Adequate but leaves the agent to infer 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 provided, so the description carries the full behavioral burden. It mentions warning/critical severity and a recommendation, which adds some output-shape context, but it does not disclose permissions, whether it merely reads (implied, not stated), read-only nature, or any server-connectivity behavior.

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

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

A single front-loaded sentence states the action, scope, and output semantics (severity + recommendation) with no filler.

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

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

Output schema exists, so return-value detail is unnecessary. For a one-parameter read tool with no annotations, the description covering action, scope, and severity/recommendation output is nearly complete, though a brief read-only assurance and server-not-found behavior would round it out.

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

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

Schema coverage is 100% with the single 'server' parameter fully documented as 'the inventory server name to check'. The description adds no parameter detail, so the baseline of 3 would apply, but with only one well-documented required parameter the schema fully compensates, meriting a 4.

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

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

Specific verb+resource ('Report per-filesystem disk usage on a Linux server') with added scope describing severity outcome. Clearly distinguishable from siblings like cpu_usage and memory_usage by signaling disk-space focus and its warning/critical interpretation.

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

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

The description implies a monitoring/diagnostic context but never states when to use this vs cpu_usage, memory_usage, or run_command for disk checks, and offers no exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full behavioral burden. It hints at scope ('local', 'on a Docker host') but says nothing about permissions or Docker socket/API access requirements, whether the image list can be large or slow, or whether host state is touched. Listing is inherently read-only, but that is left implicit.

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

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

One short sentence with zero padding, and the essential scope qualifier ('local') is included up front. It is efficient but too sparse to earn a 5.

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

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

An output schema exists, so return values need not be explained, and a single well-documented parameter keeps the signature simple. What is missing is usage context (when to prefer this over docker_ps) and any behavioral note, leaving the definition minimal but functional.

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

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

There is a single parameter ('server') and the schema already documents it at 100% coverage, so schema description coverage sets the baseline at 3. The description adds no syntax, format, or naming guidance for the server argument beyond what the schema 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 gives a specific verb and resource ('List local Docker images'), which is enough to distinguish it from docker_ps (containers), docker_logs, and docker_stats in the sibling set. It does not explicitly name any sibling or state how it differs from them, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus docker_ps, docker_stats, or run_command, and no prerequisites or exclusions are stated. The agent must infer from the name alone that this is the way to enumerate images rather than containers.

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 but does deliver useful behavioral context: logs are 'combined stdout/stderr' and 'most recent', which sets expectations for the output. It does not disclose permission requirements, behavior on a missing container, or that it is a read-only operation, leaving gaps for a no-annotation tool.

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

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

A single front-loaded sentence with zero filler, capturing the verb, resource, recency scope, and stream type efficiently.

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

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

An output schema exists, so return values needn't be explained. The description adequately conveys source (container on Docker host), scope (most recent), and stream type; the only gap is the absence of any usage routing against kubectl_logs.

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 server, container, and tail (including default) are already fully documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Fetch) and resource (combined stdout/stderr log lines) scoped to a container on a Docker host, which distinguishes it from kubectl_logs and cisco_logs/journall_errors. It does not explicitly name a sibling or clarify vs kubectl_logs, but the Docker/container anchoring is specific.

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

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

No guidance on when to use this tool versus alternatives such as kubectl_logs or journal_errors, and no prerequisites or conditions stated. Usage is only implied by the scope of the 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 behavioral burden. It usefully discloses the default filtering behavior (running containers only unless `all` is set), and 'List' implies a non-mutating read, but it says nothing about permissions, host reachability, or result size/pagination.

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

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

A single sentence with zero filler, and the default-scope nuance is placed in the parenthetical right where the reader needs it.

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

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

For a two-parameter read-only listing tool with an output schema covering return values and 100% parameter documentation, the description covers the one non-obvious behavioral nuance (default scope). Only the absence of annotation-level safety signaling keeps it from being fully complete.

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

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

Schema description coverage is 100%, so both `all` and `server` are already documented in the schema, giving a baseline of 3. The description restates the `all` toggle semantics but adds no ordering, format, or server-identification detail beyond the schema.

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

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

Specific verb+resource: 'List containers on a Docker host' immediately tells the agent this returns Docker containers, distinguishing it implicitly from docker_images, docker_logs, docker_stats and docker_restart. It stops short of explicitly naming a sibling or contrasting scope, so it is clear but not maximally differentiated.

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

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

The parenthetical conveys the default scope (running only) and the condition that widens it (`all`), which is genuine usage guidance. However, there is no statement of when to reach for this tool versus docker_stats, docker_logs or docker_restart, so selection guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does well: it flags the action as dangerous and service-impacting, explains the confirm gate and the no-op behavior when confirmation is missing, and clarifies that dry_run bypasses confirm. It omits permission/auth requirements and any cautions about container state loss, so it is not exhaustive.

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

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

Two sentences, front-loaded with the core action before the danger warning and the dry_run escape hatch. Every clause carries behavioral information; nothing is padding.

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

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

An output schema exists, so return values need not be explained, and the description covers the operation's safety contract and confirmation semantics adequately. The only gap is the absence of any note on required permissions or the blast radius of restarting a container.

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 server, container, confirm and dry_run. The description restates confirm and dry_run semantics in prose without adding format or syntax detail beyond the schema, making this the baseline case.

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

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

States a specific verb and resource ('Restart a container on a Docker host'), which cleanly distinguishes it from read-only siblings like docker_ps, docker_logs and docker_stats. An agent can identify the operation without opening the schema.

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

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

Explicitly states the precondition for acting ('requires confirm: true') and offers a safe alternative path ('Set dry_run: true to see the exact command... without needing confirm at all'). It does not name a sibling tool to use instead when a restart is the wrong choice, so it falls short of the 5-level routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the key trait that this is a 'point-in-time snapshot' (not streaming or cumulative), but it omits whether the call is read-only, any auth/permission requirements, and any rate-limit or host-reachability caveats.

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

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

A single front-loaded sentence that names the metric types and the object scope with no filler. It is appropriately sized, though it stops short of adding routing or behavioral 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?

An output schema exists, so return values need no explanation, and both parameters are fully documented in the schema. The description supplies the snapshot/semantics context an agent needs; only sibling routing and read-only/auth context are missing.

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

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

Schema description coverage is 100%, so both 'server' and 'container' are already documented in the schema, including the default-all-containers behavior. The description adds no parameter syntax or format detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (report) and resource (point-in-time CPU/memory/network/disk snapshot for containers), and the 'containers on a Docker host' scope differentiates it from host-level cpu_usage/memory_usage/disk_usage. It does not, however, explicitly name any sibling alternative to route the agent.

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

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

Use is only implied: an agent can infer you call this when you need per-container resource usage rather than host metrics or docker_ps listings. There is no explicit when-to-use, when-not-to-use, or alternative-tool guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only, point-in-time listing, but never states that (no permissions/elevation requirement, no note that it is non-mutating, no rate or scope limits), leaving the safety profile to inference.

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

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

A single front-loaded sentence with zero filler. The scope-restricting phrase ('currently in the failed state') comes early, which is exactly where an agent needs it.

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

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

For a one-parameter read tool with an output schema that already defines the return shape, the description covers what is needed to select and call it correctly. It only omits operational niceties like privilege requirements, which keeps it short of 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% — the single 'server' parameter is fully documented in the schema as 'the inventory server name to check'. The description adds no syntax, format, or sourcing detail beyond that, so the baseline 3 applies.

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

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

Specific verb ('List') plus a tightly scoped resource ('systemd services currently in the failed state'), with the platform qualifier ('on a Linux server'). This is inherently distinguishable from every sibling (journal_errors, running_processes, uptime) without opening the schema.

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

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

Usage is implied by the phrase 'currently in the failed state' — an agent infers this is for failure diagnosis on a host — but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as journal_errors for the underlying cause.

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 notes the alert states covered (firing/resolved), which is mildly useful, but says nothing about read-only safety, authentication requirements, pagination, or result limits. For a list tool with zero annotation coverage this is a notable gap.

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

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

A single front-loaded sentence with no filler; the action and resource lead and the scope qualifier follows. 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?

An output schema exists, so return-value explanation is not required, and the lone parameter is fully documented. However, the absence of any usage guidance or behavioral caveats leaves the definition only minimally complete for an alert-retrieval 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% for the single 'instance' parameter, so the schema already documents it fully. The description adds no format, naming convention, or valid-value guidance beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb ('List') and resource ('alert instances') scoped to a Grafana instance's alerting API, with the additional qualifier 'firing or resolved'. This clearly distinguishes it from siblings like grafana_dashboards, grafana_query, and grafana_annotations, though it does not explicitly name an alternative.

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

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

The description gives no indication of when to reach for this tool versus grafana_annotations or grafana_query, nor any prerequisites or filtering options. Usage is only implied by the resource name, leaving the agent to infer the 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?

With no annotations, the description carries the full behavioral burden. 'List' implies a read-only operation, which is useful, but it does not state permission requirements, pagination behavior, or result limits. The existence of an output schema relieves it of explaining return values, keeping this at a middling 3.

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

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

A single tight sentence with the action front-loaded and the optional qualifiers clearly marked. No filler or redundancy.

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

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

For a read-only listing tool with a full output schema and 100% parameter description coverage, the description covers what is needed to call it correctly. Only minor gaps remain around auth/prerequisites given the absence of annotations.

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

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

Schema description coverage is 100%, so all four parameters (tags, to_ms, from_ms, instance) are already documented in the schema including defaults and tag semantics. The description only echoes time range and tags at a high level, adding no syntax or unit detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (List) and resource (annotations) plus optional scoping, which distinguishes it from Grafana siblings like grafana_alerts, grafana_dashboards, and grafana_query by resource. It does not explicitly name those siblings, but the resource noun is unambiguous.

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

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

The phrase 'optionally scoped to a time range and/or tags' implies how the tool is used, but there is no explicit when-to-use vs when-not-to-use guidance or reference to alternatives. Adequate but leaves the agent to infer 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 behavioral burden. 'Search' weakly implies a read-only operation, but the description never states permission requirements, pagination, or whether results are scoped to a workspace. It adds little beyond the verb itself.

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 the action, target, and optional filters with zero filler. 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?

An output schema exists, so return values need not be explained, and the core search behavior is conveyed. However, for a no-annotation tool the description leaves behavioral gaps (auth, pagination, result scope) that an agent might need when invoking it.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (tag, query, instance). The description restates that filters exist (title text, tag) but adds no syntax, format, or matching semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb (Search) applied to a clear resource (dashboards) on a Grafana instance, which distinguishes it from siblings like grafana_alerts and grafana_annotations. It does not explicitly name those siblings, so it falls just short of a 5.

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

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

'Optionally filtered by title text or tag' implies the browsing use case and gives a sense of when the filters apply, but there is no explicit when-to-use, exclusion, or named alternative against grafana_query or grafana_alerts. Usage is only implied.

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

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

With no annotations, the description carries the full burden, and it does disclose a genuinely non-obvious trait: the response shape is datasource-specific and un-normalized, so callers cannot assume a uniform result. It omits other behavioral context such as read-only semantics, error behavior, or query timeouts/limits, so it falls short of fully covering a raw-query 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 filler. The core action is front-loaded and the caveat about response shape follows immediately, which is the right ordering for an agent skimming for intent.

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

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

An output schema exists and the description still usefully warns that the payload is datasource-specific, and 100% parameter coverage means the schema handles inputs. For a tool spanning Prometheus/Loki/SQL it could say more about the datasource types it supports or whether the query is read-only, but what is present is adequate to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the from/to time defaults and the datasource UID. The description adds no parameter-level meaning beyond telling the agent the result varies by datasource type, so the baseline 3 applies.

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

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

States a specific verb+resource ('Run a raw query against one datasource') and clarifies the scope is a single datasource on a Grafana instance. It does not explicitly contrast itself with sibling tools like grafana_alerts or grafana_dashboards, so an agent must infer the boundary from the word 'raw'.

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

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

Usage is only implied: the agent can infer this is for datasource-native queries rather than the specialized Grafana siblings, but there is no explicit when-to-use/when-not statement or named alternative. The 'passthrough' framing hints at intent without spelling out the selection rule.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the useful filtering behavior (error priority or higher) and recency ordering, but says nothing about read-only nature, permissions, or result volume beyond the schema's limit parameter.

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 wasted words. The filtering constraint and target host type are stated immediately.

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

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

For a simple two-parameter read tool with an output schema covering the return values, the description is nearly sufficient. The main gap is the absence of when-to-use routing among the many log-related siblings.

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

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

Schema description coverage is 100%, so both server and limit are already well documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb (report), resource (systemd journal entries), filter (error priority or higher), and scope (Linux server), so the agent knows exactly what this returns. It does not explicitly contrast itself with the log-oriented siblings like docker_logs, kubectl_logs, or cisco_logs, so it stops 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?

There is no statement of when to use this tool versus the other log-reading siblings (docker_logs, kubectl_logs, cisco_logs) or failed_services. Usage is only weakly implied by the 'error priority or higher' filter, and no exclusions or prerequisites are given.

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

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

No annotations are provided, so the description carries the burden. 'Report' implies a read-only, non-mutating call and the command is disclosed, but there is no mention of permission requirements or remote-execution caveats. Adequate for a trivial read, but thin.

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

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

One front-loaded sentence with no waste; the parenthetical command is the most useful token in the definition and is included without padding.

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

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

A single-parameter, read-only tool with an output schema that carries the return values. The description covers the essential framing (Linux, kernel release), though it could note that the target must be a reachable inventory server.

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

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

Schema description coverage is 100% and the single parameter 'server' is documented in the schema, so the baseline is 3. The description adds only the framing that the server is Linux rather than any new parameter-level detail.

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

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

States a specific verb ('Report') and resource ('the running kernel release'), with the exact command (`uname -r`) as ground truth, which clearly distinguishes it from siblings like uptime or cisco_version. It doesn't explicitly name a sibling, so a 4 rather than 5.

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

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

Usage is implied by the 'of a Linux server' qualifier, but there is no explicit when-to-use or when-to-prefer-an-alternative guidance (e.g., vs uptime or cisco_version). The agent can infer intent but must do so 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?

No annotations are provided, so the description carries the full burden. It discloses the return content (spec/status highlights plus recent events), which is genuine behavioral value, but says nothing about read-only nature, required permissions, or whether events retrieval is bounded/paginated.

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

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

A single front-loaded sentence that identifies the resource and its output with zero filler. Nothing is wasted and the key information comes first.

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

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

An output schema exists, so the description need not explain return values, and all parameters are covered by the schema. What remains is the absence of annotation coverage for read-only/permission context, but for a describe-style inspection tool the definition is essentially complete.

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

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

Schema description coverage is 100%, so all three parameters (cluster, namespace, pod) are already documented in the schema. The description adds no additional syntax, format, or defaulting guidance beyond what the schema provides, making the baseline 3 correct.

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 ("Describe a pod") and even previews the content it returns (spec/status highlights + recent events), so the agent knows this is a detail-oriented inspection tool rather than a listing tool. It never names or distinguishes itself from siblings like kubectl_get_pods or kubectl_events, whose scope partially overlaps with the events it mentions.

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

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

Usage is only implied: an agent can infer you call this to inspect a single pod, but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g., use kubectl_get_pods for listing, kubectl_logs for logs). Adequate but leaves selection to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses sort order (most recent first) and that the default is all namespaces, but says nothing about how many events are returned, any time window, result caps/truncation, or required permissions.

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

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

A single front-loaded sentence with the core action, ordering, and scope; 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?

An output schema exists, so return values need not be described, and both parameters are fully documented in the schema. The remaining gap is behavioral (result volume, time window) rather than structural, leaving it nearly complete for a simple list 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 both 'cluster' and 'namespace' are already documented, including the default of all namespaces. The description restates the namespace scoping without adding syntax, format, or behavior beyond the schema; baseline 3 applies.

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

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

States a specific verb (List) and resource (Kubernetes events) plus the ordering guarantee ('most recent first') and scope ('optionally scoped to one namespace'). It is clearly distinguishable from kubectl_logs or kubectl_describe by resource, though it never names a sibling or contrast case.

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

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

Usage is only implied: 'recent events' suggests troubleshooting/cluster-health triage, and the namespace scoping hints at a filtering workflow. There is no explicit when-to-use, when-not-to-use, or pointer to alternatives like kubectl_describe or kubectl_logs for deeper diagnosis.

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 disclosure burden. 'List' implies a safe, non-mutating read, which is the key behavioral fact for this tool, but it says nothing about authentication/credential requirements, whether the query is cluster-wide by default affecting cost/latency, or pagination behavior.

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

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

A single front-loaded sentence with the resource stated first and the scope qualifier second. Nothing is wasted, though the trailing clause largely echoes the namespace parameter's own schema description.

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

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

An output schema exists, so return values need not be explained, and the tool is a simple two-parameter read with full schema coverage. The remaining gap is environmental context (which cluster/credential the agent must supply and default cluster-wide behavior), which is minor for a list operation.

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

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

Schema description coverage is 100%, and both parameters are already documented (cluster name, namespace with 'default: all namespaces'). The description only restates the namespace scoping and adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List pods in a Kubernetes cluster') plus an explicit scope modifier (optional namespace). This clearly separates it from sibling kubectl tools like kubectl_nodes, kubectl_logs, and kubectl_describe, though it never names those siblings explicitly to sharpen the boundary.

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

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

The optional-namespace phrasing implies when to narrow the query, but there is no explicit guidance on when to use this versus kubectl_describe, kubectl_events, or kubectl_logs, nor any stated prerequisites (cluster credentials/context). Usage is inferable from the resource name rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It only says 'Fetch,' implying a read-only operation, but omits auth requirements, rate limits, behavior for multi-container pods, or whether the call is streaming versus snapshot.

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

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

A single front-loaded sentence with zero waste. It states the action and resource immediately and contains no redundant or filler content.

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

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

An output schema exists, so return values need not be described, and schema coverage is full. However, with no annotations and no usage guidance, the description does not fully compensate for the missing behavioral and routing context an agent needs among multiple log-fetching siblings.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including defaults for 'tail' and 'container'. The description adds no parameter semantics beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb ('Fetch') and resource ('log lines from a pod's container in a Kubernetes cluster'). The resource scope naturally distinguishes it from sibling tools like docker_logs, cisco_logs, kubectl_describe, and kubectl_events.

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

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

No when-to-use guidance, prerequisites, or alternative tools are mentioned. The description implies usage context but provides no explicit routing information for an agent choosing among the many log-related siblings.

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

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

No annotations are provided, so the description carries the full burden. 'List' signals a read-only, non-destructive operation and the description discloses which node attributes come back, but it says nothing about cluster connectivity, credentials, failure modes, or pagination/scale limits.

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

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

A single front-loaded sentence with zero filler: verb, resource, scope, then value-add attributes. Nothing is wasted, though it is arguably a touch terse for a tool with no annotations to lean on.

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

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

An output schema exists, so return values need not be explained, and the single required parameter is fully covered by the schema. The description is complete enough for a simple read-only list tool; the only gap is behavioral context that annotations would normally supply.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents 'cluster' as the inventory cluster name. The description adds no extra meaning about that parameter, which is the expected baseline when the schema does the work.

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

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

Specific verb ('List') plus resource ('nodes') and scope ('in a Kubernetes cluster'), with the returned attributes (readiness, roles, capacity) enumerated. It is clearly separable from kubectl_get_pods and proxmox_nodes, though it never names a sibling to contrast against.

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 listing intent implies when it is useful, but there is no explicit when/when-not guidance and no mention of alternatives such as kubectl_describe or kubectl_events for deeper per-node detail. Usage is only implied by the resource name.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely useful, non-obvious trait — "Never returns credentials" — but says nothing about whether the call is read-only, how large the result can get, or whether the inventory is queried live or cached.

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, no filler, with the core action first and the security guarantee placed last where it reads as a guarantee rather than the main point. 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?

An output schema exists, so return values need no explanation, and the parameter is fully documented in the schema. The description covers the action, the filter, and one behavioral caveat; only the read-only nature of the call is left implicit, which is minor for a list operation.

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

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

Schema coverage is 100% for the single optional tag parameter, so the schema already documents its meaning fully. The description confirms the tag filter exists but adds no syntax, matching rules, or case-sensitivity detail beyond it. Baseline 3 applies.

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

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

The description states a specific verb and resource ("List servers known to the inventory") and names the supported filter, so the operation is unambiguous. It does not, however, distinguish itself from the closest sibling, cisco_inventory, which an agent could plausibly confuse for a server listing.

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

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

"Optionally filtered by tag" implies the common usage pattern, and the schema's own description clarifies that omitting the tag returns everything. There is no explicit when-to-use guidance, no mention of when a different sibling (e.g. cisco_inventory) would be the better pick.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses that output includes a warning/critical severity and a recommendation when memory is low, but it omits read-only confirmation, permission requirements, and whether it runs remotely or locally.

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

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

A single compact sentence that front-loads the action and resource with no wasted words.

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

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

For a single-parameter read-only diagnostic with an output schema, the description covers the essentials and even hints at return content (severity/recommendation). Minor gaps in host targeting and read-only confirmation 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?

Only one parameter exists and the schema documents it fully (100% coverage), so the description is not required to add syntax. It adds no meaning beyond the schema's 'inventory server name', making the baseline 3 appropriate.

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

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

States a specific verb (report) and resource (memory usage) scoped to a Linux server, and mentions the warning/critical severity framing. This clearly distinguishes it from sibling diagnostics like cpu_usage and disk_usage.

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

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

Usage is implied by the name and purpose (check memory on a host), but there is no explicit when-to-use/when-not guidance and no reference to alternative tools such as cpu_usage or disk_usage for other resource checks.

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. 'List' implies a read operation and it discloses the return content ('resource usage summary'), but it says nothing about authentication requirements, permissions, cluster-connectivity caveats, or output shape beyond that phrase. Adequate but thin for an unannotated 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 well-formed sentence that front-loads the action and resource and ends with the payload detail. No filler, no 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?

The tool is simple (one required param) and has an output schema, so return values need not be explained. The description covers the essential what-and-what-you-get, leaving only usage routing unaddressed, which is a minor completeness gap rather than a critical one.

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

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

There is one parameter ('instance') and schema description coverage is 100%, so the schema already documents it. The description adds no syntax, format, or naming guidance for selecting the instance, which matches the baseline 3 for high-coverage schemas.

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 ('List') and resource ('every node in a Proxmox VE cluster') plus the returned payload ('resource usage summary'). It is clearly distinct from siblings like proxmox_vms, but it never explicitly names or contrasts with those siblings, so it stops short of a 5.

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

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

There is no guidance on when to use this versus alternatives. The agent must infer from the resource name that this lists cluster nodes, and the description never mentions exclusions, prerequisites, or related tools such as proxmox_vms or proxmox_tasks.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that this is state-changing, that it no-ops without confirm, that the success response is a UPID rather than completion, and that dry_run bypasses confirmation. This is exactly the context an agent needs to avoid assuming the snapshot finished.

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, zero filler, and the most important constraint (state-changing, needs confirm) is front-loaded before the async and dry_run details. Each sentence delivers a distinct operational fact.

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

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

An output schema exists, yet the description goes further by interpreting the asynchronous UPID return and pointing to the tool that resolves it. Combined with the confirmation and dry_run semantics, nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including confirm and dry_run. The description restates the confirm/dry_run contract in behavioral terms but adds no syntax, constraints, or default details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Take a snapshot of a QEMU VM or LXC container on a Proxmox node') and scopes it to both guest types. No sibling tool performs snapshots, so the agent can distinguish it immediately from proxmox_start_vm, proxmox_stop_vm, or proxmox_tasks.

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

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

Clearly explains the gating condition (confirm: true required, otherwise it reports and returns) and names proxmox_tasks as the way to follow up on the async operation, plus dry_run as a no-confirm preview path. It lacks an explicit 'use this before making changes' framing, but the when/how conditions are concrete.

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

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

With no annotations, the description carries the full burden and does so well: it declares the call state-changing, that it silently no-ops without confirm:true, that the operation is asynchronous returning a UPID rather than a completion signal, and that dry_run bypasses confirm entirely. These are exactly the traits an agent needs before firing a mutation.

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

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

Four tight sentences, purpose front-loaded, then preconditions, async caveat, and dry_run alternative in descending order of importance. No filler or repetition.

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

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

For a mutating tool with an output schema, the description supplies everything the schema cannot: confirmation gating, the no-op-on-missing-confirm behavior, async/UPID semantics, and the follow-up tool. Return-value detail is legitimately left to the output schema.

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

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

Schema description coverage is 100%, so confirm and dry_run semantics are already fully documented in the schema and the description largely restates them. It adds no format or value constraints beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (Start) and resource (QEMU VM or LXC container on a Proxmox node), and the scope is precise enough to separate it from sibling proxmox_stop_vm without opening any schema. Nothing tautological or vague.

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

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

Explains the confirm-gating precondition, the dry_run escape hatch, and points to proxmox_tasks for follow-up, which is clear operational context. It does not explicitly contrast against proxmox_stop_vm or other lifecycle siblings, so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the full burden and does so well: it declares the action dangerous and service-impacting, states the confirm requirement and what happens without it, explains the asynchronous return (UPID, not confirmation), and points to proxmox_tasks for verification. It also explains dry_run's effect on the confirm requirement. This is more behavioral context than most mutation tools provide.

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

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

Three sentences, each front-loaded and purposeful: the action and its semantics, the danger/confirmation gating, then the async caveat and dry_run escape hatch. No filler, no repetition of schema fields.

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

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

For a destructive, no-annotation, async mutation tool, the description covers danger, confirmation gating, async result handling with a named sibling, and a dry-run alternative. An output schema exists, so return value details are not needed in the description. Nothing an agent needs to call this safely is missing.

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

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

Schema description coverage is 100%, so the schema already documents node, type, vmid, confirm, dry_run, and instance. The description adds meaning for confirm and dry_run (what they gate and return), but doesn't elaborate on node/type/vmid beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (force-stop) and resource (QEMU VM or LXC container on a Proxmox node), and immediately clarifies the semantics of 'stop' as hard power-off rather than graceful shutdown. This distinguishes it from the sibling proxmox_start_vm and from any graceful shutdown concept.

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

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

Explicitly states the gating condition (requires confirm: true, otherwise it returns without acting) and mentions dry_run as a safe alternative for inspecting the call. It routes the agent to proxmox_tasks for checking the asynchronous result. However, it doesn't explicitly compare against a graceful shutdown sibling (none is listed), so the when-not guidance is implicit.

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

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

With no annotations, the description carries the full burden, and it does disclose the 'most recent first' ordering, which is useful behavioral context. However, it does not state that this is a read-only listing, note any pagination or rate-limit behavior, or mention the default cap (`limit`) semantics beyond what the schema already says.

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

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

A single sentence, front-loaded with the verb and resource, with the ordering behavior appended and zero filler. Every clause earns its place.

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

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

For a simple read-only listing tool with full schema coverage and an output schema, the description covers the essential purpose, scope, and ordering. Minor omissions (explicit read-only nature, pagination/limit interaction) keep it just short of complete.

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

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

Schema description coverage is 100%, so `node`, `limit`, and `instance` are already fully documented in the schema, and an output schema exists. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('List') with a clearly scoped resource ('recent tasks ... recorded on a Proxmox node') and even enumerates task types (backups, migrations, VM actions). This is readily distinguishable from siblings like proxmox_vms or proxmox_nodes, though it does not explicitly name them to reinforce the distinction.

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

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

Usage is only implied: an agent can infer this is for inspecting node task history, but there is no statement of when to prefer this over alternatives or any exclusions/prerequisites. Adequate but with a clear 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 must carry behavioral disclosure; it does convey that this is a read-only enumeration scoped to a single node. It does not address pagination, result limits, permissions required, or what happens if the node name is invalid. For a low-risk list operation the scope statement is adequate but thin.

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

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

A single front-loaded sentence with no filler; the resource and scope appear immediately. It is efficient, though almost too terse to stand alone without 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?

An output schema exists, so return values need not be explained, and the tool is a simple two-parameter read. What is missing is the instance-to-node relationship and any usage routing against proxmox_nodes, leaving the definition minimally 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% and both parameters (node, instance) are documented in the schema, so the baseline is 3. The description echoes the node scoping but adds nothing about the 'instance' parameter or the relationship between instance and node.

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

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

The description names a specific verb ('List') plus both resources it covers (QEMU VMs and LXC containers) and the scope ('on a Proxmox node'). It is clearly distinct from siblings like proxmox_start_vm, proxmox_stop_vm, proxmox_snapshot, and proxmox_nodes, though it never explicitly contrasts itself with proxmox_nodes (which lists nodes rather than guests).

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites (e.g. that the node must belong to the named instance), and no exclusions. The listing intent is only implied by the verb 'List'.

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

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

With no annotations, the description carries the full behavioral burden. It helpfully discloses the detection logic (Debian/Ubuntu reboot-required marker vs. running-kernel-older-than-newest), but does not state read-only safety, needed permissions, or whether the check is costly. Some genuine value, clear gaps remain.

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

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

A single sentence, front-loaded with the verb and outcome, with the clarifying detail parenthesized. Zero wasted words.

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

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

An output schema exists, so return values need not be explained, and the tool takes one simple parameter. The description covers the concept and detection method well; only minor gaps around permissions/behavior remain.

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

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

Schema coverage is 100%, so the single 'server' parameter is already fully documented in the schema. The description adds no format, naming, or resolution detail beyond it, matching the baseline when the schema does the heavy lifting.

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

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

States a specific verb (Report) and a precisely scoped resource: whether a Linux server is pending a reboot. The parenthetical even names the two detection mechanisms, making it easy to distinguish from siblings like kernel_version or uptime.

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

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

Usage is implied by the clear scope, but there is no explicit when-to-use or when-not-to-use guidance, and it never routes the agent away from the closely related kernel_version sibling. Adequate but leaves the choice to inference.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the sort order and implicitly that this is a read operation, but says nothing about required server access/credentials, whether output is truncated beyond the limit, or any rate limits.

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

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

A single front-loaded sentence with no filler; the ordering constraint is stated in the same breath as the purpose. Nothing is wasted.

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

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

An output schema exists, so return-value explanation is not needed, and the parameters are fully documented. However, for a tool that reaches out to a named inventory server, the description omits any note about connectivity, authentication, or failure modes, leaving it only minimally complete.

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

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

Schema description coverage is 100%, so both 'server' and 'limit' are already documented in the schema, including the default of 20 and the CPU-descending sort. The description adds no parameter detail beyond what the schema provides, so the baseline of 3 applies.

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

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

Clear verb+resource ('List the top processes') with the ordering stated explicitly, so an agent knows exactly what it returns. It does not, however, distinguish itself from nearby siblings such as cpu_usage or docker_ps, which an agent might otherwise confuse for process-level listing.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative tools are named. The agent must infer from the name alone that this is for per-process CPU analysis rather than aggregate CPU reporting.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Report' implies a non-mutating read, but the description does not state permissions, prerequisites, failure modes, or whether the target must be in inventory. It is adequate for a simple read-only diagnostic, 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?

The description is a single, front-loaded sentence with no wasted words. It communicates the action and the exact metrics returned immediately.

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

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

For a simple read-only diagnostic with a fully documented single parameter and an output schema, the description is nearly complete. It explains what is measured but omits any prerequisite or error-handling context, leaving a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents the single required 'server' parameter as an inventory server name. The description adds no further parameter meaning beyond reinforcing that the target is a Linux server, so baseline 3 is appropriate.

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

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

The description states a specific reporting action and two concrete outputs: server uptime and 1/5/15-minute load averages. It clearly distinguishes itself from sibling diagnostic tools like cpu_usage, memory_usage, and kernel_version, though it does not explicitly name alternatives.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The description does not tell the agent how this differs from or complements sibling tools such as cpu_usage or running_processes, leaving usage context to inference.

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